webhooks

BeeL Webhook Receiver

Build or fix a webhook receiver that BeeL can deliver to safely. An unverified or non-idempotent receiver is worse than polling — it can be fed a fake invoice.issued from anyone, or double-process events.

The base pattern (Express example) lives in ../beel-api/recipes/webhook-handler.md. This skill adds the full procedure around it: live event catalog, framework gotchas, subscription management and end-to-end verification.

Procedure

1. Fetch the current event catalog

Event types and payload schemas change — discover and fetch the webhook doc pages before writing handlers:

curl -s https://docs.beel.es/llms.txt | grep -i webhook

Fetch the events page (types + payloads) and, if anything below fails, the signatures/deduplication/retries pages.

2. Implement verification (non-negotiable, first middleware)

Stable invariants (re-verify against the live signature docs if anything fails):

• Header: BeeL-Signature: t=<unix_ts>,v1=<hex_digest>
• Digest: HMAC-SHA256 over the string "<timestamp>.<raw_body>", hex-encoded, keyed with the webhook secret (provided at subscription creation; store in an env var)
• Reject when |now - t| > 300 seconds (replay window)
• Compare with a constant-time function (crypto.timingSafeEqual), never === — and guard buffer lengths first, since timingSafeEqual throws on mismatched lengths
• Return 401 on verification failure, before touching the payload

In Node, check whether the official SDK (@beel_es/sdk) verification helper fits before hand-rolling — fetch the live SDK docs for its current API.

The #1 pitfall — raw body. The HMAC covers the raw bytes. JSON middleware that parses before verification breaks it:

• Express: use express.raw({ type: 'application/json' }) on the webhook route, parse JSON only after verifying (and keep any global express.json() off this route)
• Next.js (App Router): use await req.text() for verification, then JSON.parse
• Fastify: use a content-type parser that preserves the raw buffer