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. While wiring up verification, it helps to inspect the payload in our webhook tester so you can see the exact headers and body bytes fal.ai is sending before your code ever runs.

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 →