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