fal.ai Webhooks: A Complete Guide

Updated October 03, 20258 min read

Fal.ai webhooks provide a powerful way to get notified about events in your machine learning models, like when a request is done processing. This guide will walk you through receiving and verifying fal.ai webhooks.

What are fal.ai Webhooks?

A fal.ai webhook is a POST request sent to a URL you provide. It's triggered when a long-running process, like model training, completes. Instead of polling for results, fal.ai pushes the results to your application.

Setting Up a Webhook

To receive webhooks, you need to provide a `fal_webhook` query parameter when making a request to the `queue.fal.run` endpoint.

curl --request POST \ --url 'https://queue.fal.run/fal-ai/flux/dev?fal_webhook=https://url.to.your.app/api/fal/webhook' \ --header "Authorization: Key $FAL_KEY" \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Photo of a cute dog" }'

Webhook Payload

Successful Result

A successful webhook payload will have a status of "OK" and include the results of your request.

{ "request_id": "123e4567-e89b-12d3-a456-426614174000", "gateway_request_id": "123e4567-e89b-12d3-a456-426614174000", "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 Result

If an error occurs, the status will be "ERROR" and the payload will contain error details.

{ "request_id": "123e4567-e89b-12d3-a456-426614174000", "gateway_request_id": "123e4567-e89b-12d3-a456-426614174000", "status": "ERROR", "error": "Invalid status code: 422", "payload": { "detail": [ { "loc": ["body", "prompt"], "msg": "field required", "type": "value_error.missing" } ] } }

Verifying Webhook Signatures

To ensure that incoming webhooks are from fal.ai, you should verify the signature of each request. Fal.ai uses a `X-Fal-Webhook-Signature` header.

The verification process involves several steps:

  • Fetch the JSON Web Key Set (JWKS) from fal.ai.
  • Extract headers from the incoming request.
  • Verify the timestamp of the request.
  • Construct the message to verify.
  • Verify the signature using the public key.

JavaScript Example

const crypto = require('crypto'); const sodium = require('libsodium-wrappers'); const fetch = require('node-fetch'); const JWKS_URL = 'https://rest.alpha.fal.ai/.well-known/jwks.json'; async function verifyWebhookSignature(requestId, userId, timestamp, signatureHex, body) { await sodium.ready; // 1. Validate timestamp const timestampInt = parseInt(timestamp, 10); const currentTime = Math.floor(Date.now() / 1000); if (Math.abs(currentTime - timestampInt) > 300) { return false; } // 2. Construct the message const messageParts = [ requestId, userId, timestamp, crypto.createHash('sha256').update(body).digest('hex') ]; const messageToVerify = messageParts.join('\n'); const messageBytes = Buffer.from(messageToVerify, 'utf-8'); const signatureBytes = Buffer.from(signatureHex, 'hex'); // 3. Fetch public keys const response = await fetch(JWKS_URL); const jwks = await response.json(); // 4. Verify signature for (const keyInfo of jwks.keys) { const publicKeyB64Url = keyInfo.x; const publicKeyBytes = Buffer.from(publicKeyB64Url, 'base64url'); if (sodium.crypto_sign_verify_detached(signatureBytes, messageBytes, publicKeyBytes)) { return true; } } return false; }

Master Webhook Development with Hooklistener

Hooklistener provides the complete webhook development and debugging platform. Capture, inspect, replay, and monitor webhooks with signature verification, team collaboration, and production-ready reliability.

Start Building Webhooks Free →