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

TL;DR

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.

Steps

1. 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.

When to use

You are seeing this: 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. Use this skill when you run into "fal webhooks: verify the ED25519 signature yourself, and only send keys to fal hosts".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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