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.

To utilize webhooks, your requests should be directed to the queue.fal.run endpoint, instead of the standard fal.run. This distinction is crucial for enabling webhook functionality, as it ensures your request is handled by the queue system designed to support asynchronous operations and notifications.

curl --request POST \
  --url https://queue.fal.run/fal-ai/fast-svd\?fal_webhook\=https://url.to.your.app/api/fal/webhook \
  --header "Authorization: Key $FAL_KEY" \
  --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.

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"
}