Human guide
Read the reasoning behind raw-body verification, durable acknowledgement, deduplication, retries, and provider registration.
Rails Implementation Guide · $12
Webhooks in Rails
Receiving a webhook is easy. The code that still works when it arrives twice, arrives out of order, or fails halfway through is where things get interesting.
The guide is written for a human who needs to understand the boundaries. The companion gives a coding agent explicit contracts, examples, and review questions to consult while it extends an existing Rails application.
Six chapters + debugging appendix · PDF, EPUB, and HTML · Agent Companion included
The guide and the companion
One explains the decisions. The other gives the next change somewhere to start.
Webhooks in Rails is a human guide first. It walks through the request boundary, the delivery record, the job, and the handler so you can make the tradeoffs deliberately.
The Agent Companion turns those decisions into small, inspectable entrypoints: contracts to check, recipes to adapt, examples to compare, and a review checklist for the work that comes back.
It is for brownfield Rails work. Start with the application you already have, map its conventions, and adapt the companion’s patterns. This is context for an agent, not a promise that an unfamiliar codebase can accept a drop-in patch.
Agent Companion
Give a capable agent explicit places to look before it changes a webhook flow, with room for you to review every boundary.
The POST is the easy part
Build the part that survives production.
Signatures are calculated over raw bytes. Parse too early or compare the wrong thing and a valid request looks fake.
Provider retries and queue retries happen on opposite sides of your successful HTTP response. The handoff needs to be durable.
Webhook delivery is at-least-once. Use a real database uniqueness boundary instead of hoping an exists? check wins a race.
Received is not processed. A failed job should leave enough state to retry the work instead of accidentally skipping it forever.
One Rails shape, two providers
See the common pattern instead of memorizing one vendor.
Provider→Rails route→Verify signature→Delivery record→Job→Handler
Use the SDK, understand the boundary.
Stripe-SignatureStripe::Webhook.construct_event- Stripe Event IDs for delivery-level deduplication
- Stripe CLI for local forwarding and debugging
Build the verification yourself.
X-Hub-Signature-256- HMAC-SHA256 over
request.raw_post X-GitHub-Deliveryas the delivery identifier- Programmatic hook creation and removal with Octokit
What's inside
Short enough to finish. Deep enough to use.
Webhooks Without the Mystery
Machine endpoints, raw request bodies, acknowledgement boundaries, and why duplicate delivery is normal.
Receiving a Real Webhook with Stripe
Verify Stripe signatures, persist a durable delivery, hand work to Active Job, and keep the HTTP response fast.
Make It Safe to Retry
Separate received from processed, close concurrency races with database constraints and locks, and keep failures retryable.
Verify Webhooks Yourself with GitHub
Calculate HMAC-SHA256 over the exact request body, use delivery GUIDs correctly, and dispatch verified events.
When Your App Has to Register the Webhook
Create, update, and remove provider-side hooks through Octokit without pretending two systems share a transaction.
Testing Webhooks Without Hating Your Life
Request specs for signatures and malformed bodies, job retry specs, WebMock, and provider registration tests.
Debugging Webhooks
The appendix follows one delivery from the provider dashboard through Rails and Solid Queue, covers tunnels and replay, and shows where an inspection tool such as CatchHook fits without making the architecture depend on it.
What $12 includes
A guide to read, and a companion to use.
Understand the webhook lifecycle.
- PDF, EPUB, and HTML editions
- Six focused chapters
- A debugging appendix
- Concrete Stripe and GitHub examples
Give the next change a local shape.
- Contracts for receipt, verification, processing, and retry
- Stripe and GitHub recipes, plus a path for another provider
- Portable implementation examples to inspect before implementing
- A review checklist for correctness and failure boundaries
AGENTS.mdandCLAUDE.mdentrypoints
What the guide cares about
Correctness around the ugly edges.
The examples separate delivery identity from business-object identity, put a UNIQUE index behind deduplication, mark work processed only after it succeeds, and keep remote API calls outside database locks.
It also covers out-of-order events, payload retention, idempotency for external side effects, explicit operator retries, and why provider registration has its own failure lifecycle.
webhook lifecycle
received
↓
processing
├──→ processed
└──→ failed
↓
retryWebhooks in Rails
Build webhook code you can trust when the happy path stops being happy.
Six focused chapters, a debugging appendix, and an Agent Companion with contracts, provider recipes, examples, review checks, and AGENTS.md / CLAUDE.md entrypoints.