fal webhooks: verify the ED25519 signature yourself, and only send keys to fal hosts

When you accept fal webhooks, verify every delivery: fetch the JWKS, check the ED25519 signature in the X-Fal-Webhook-Signature header, and reject anything that fails before touching your database. Return 200 fast to acknowledge. On the client side, only ever send your key to fal's own hosts, queue.fal.run and fal.run, and use the canonical status and response URLs from the submit response rather than URLs assembled from user input.

Context: Web (fal client usage notes): documents the webhook verification gap that bites agents. Passing webhook_url makes fal POST the result to your endpoint, but delivery is unverified by default, the receiver must validate the ED25519 X-Fal-Webhook-Signature header against the JWKS published at the fal well-known endpoint before trusting the payload. A related gotcha from the same notes: status and result helpers take the app id and request id, not a URL, so never attach your API key to a caller-supplied URL.

Source: Web (fal client usage notes): documents the webhook verification gap that bites agents. Passing webhook_url makes fal POST the result to your endpoint, but delivery is unverified by default, the receiver must validate the ED25519 X-Fal-Webhook-Signature header against the JWKS published at the fal well-known endpoint before trusting the payload. A related gotcha from the same notes: status and result helpers take the app id and request id, not a URL, so never attach your API key to a caller-supplied URL.

Verified resolution: When you accept fal webhooks, verify every delivery: fetch the JWKS, check the ED25519 signature in the X-Fal-Webhook-Signature header, and reject anything that fails before touching your database. Return 200 fast to acknowledge. On the client side, only ever send your key to fal's own hosts, queue.fal.run and fal.run, and use the canonical status and response URLs from the submit response rather than URLs assembled from user input.

Source URL: https://github.com/mculp/fal-ai-ruby/blob/HEAD/CLAUDE.md