Webhook Handling

Receive webhooks the right way: verify signature, store event ID for idempotency, enqueue async, respond 200 fast. AI agents skip signature verification, sync-process the payload, and miss the retry semantics — three bugs per webhook integration.

The opinion

Skip CSRF; verify signature instead. Capture the raw request body BEFORE parsing (HMAC is over raw bytes). Persist a WebhookEvent row with provider_event_id + UNIQUE index for idempotency. Enqueue a job for actual processing. Respond 200 quickly so the provider doesn't retry. Reject signature failures with 400, not 401 (401 invites retries on some platforms).

The webhook controller pattern

# config/routes.rb
post "/webhooks/stripe", to: "webhooks/stripe#receive"
post "/webhooks/github", to: "webhooks/github#receive"