favro-webhooks

Favro Webhooks

When to Use This Skill

• How do I receive Favro webhooks?
• How do I verify the Favro X-Favro-Webhook signature?
• Why is my Favro webhook signature verification failing?
• How do I respond to the Favro setup ping so the webhook validates?
• How do I handle card.created, card.committed, card.moved, card.updated, card.deleted events?
• How do I handle comment.created, comment.updated, comment.deleted events?

How Favro Webhooks Work (Read This First)

Favro does not use the Standard Webhooks spec. Its signature scheme is unusual in one critical way: the signed message is not the request body. From the Favro developer docs:

The header is a base64 digest of an HMAC-SHA1 hash. The hashed content is the concatenation of the payloadId and the URL exactly as it was provided during webhook creation. The key used to sign this text is the secret you entered when setting up the webhook.

So verification requires three inputs — and the body is not one of them:

X-Favro-Webhook = base64( HMAC-SHA1( key = secret, message = payloadId + webhookUrl ) )
                                                              └─ from body ─┘  └─ from config ─┘

Two consequences drive everything below:

1. You must know the exact URL you registered. The webhookUrl in the HMAC is the postToUrl you gave Favro verbatim — same scheme, host, path, trailing slash, and query string. Store it as an env var (FAVRO_WEBHOOK_URL) and keep it byte-identical to what you registered, or every signature will mismatch.
2. The payloadId comes from the JSON body. Every delivery (including the setup ping) carries a top-level payloadId string. Parse it out, concatenate payloadId + webhookUrl, and HMAC that — not the body bytes.

Favro ──POST {"payloadId":"…","action":"…", …}──▶ your endpoint
              X-Favro-Webhook: <base64 HMAC-SHA1>      │  expected = base64(HMAC-SHA1(secret, payloadId + FAVRO_WEBHOOK_URL))
                                                        ▼  timing-safe compare to header
                                          valid? → dispatch on action → 200
                                          ping?  → 200 (validates the webhook)