Webhooks

Webhooks work in tandem with the queue system explained above, it is another way to interact with our queue. By providing us a webhook endpoint you get notified when the request is done as opposed to polling it.

Here is how this works in practice, it is very similar to submitting something to the queue but we require you to pass an extra fal_webhook query parameter.

curl --request POST \
  --url https://110602490-lora.gateway.alpha.fal.ai/fal/queue/submit\?fal_webhook\=https://url.to.your.app/api/fal/webhook \
  --header "Authorization: Key $FAL_KEY_ID:$FAL_KEY_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "model_name": "stabilityai/stable-diffusion-xl-base-1.0",
  "prompt": "Photo of a cute dog"
}'

The request will be queued and you will get a response with the request_id:

{
  "request_id": "024ca5b1-45d3-4afd-883e-ad3abe2a1c4d"
}

Once the request is done processing in the queue, a POST request is made to the webhook URL, passing the request info and the resulting payload. The status indicates whether the request was successful or not.

When to use it?

Webhooks are particularly useful for requests that can take a while to process and/or the result is not needed immediately. For example, if you are training a model, which is a process than can take several minutes or even hours, webhooks could be the perfect tool for the job.

Successful result

The following is an example of a successful request:

{
  "request_id": "024ca5b1-45d3-4afd-883e-ad3abe2a1c4d",
  "status": "OK",
  "payload": {
    "images": [
      {
        "url": "https://url.to/image.png",
        "content_type": "image/png",
        "file_name": "image.png",
        "file_size": 1824075,
        "width": 1024,
        "height": 1024
      }
    ],
    "seed": 196619188014358660
  },
  "error": null
}

Errors

When an error happens, the status will be ERROR. The error property will contain a message and the payload will provide the error details. For example, if you forget to pass the required model_name parameter, you will get the following response:

{
  "request_id": "024ca5b1-45d3-4afd-883e-ad3abe2a1c4d",
  "status": "ERROR",
  "payload": {
    "detail": [
      {
        "loc": ["body", "model_name"],
        "msg": "field required",
        "type": "value_error.missing"
      }
    ]
  },
  "error": "Invalid status code: 422"
}

Queue Client