Your Webhook Endpoint is a Tiny Distributed System

If you want the Rails implementation version of this, Webhooks in Rails goes deeper on verification, durable receipt, idempotency, retries, jobs, testing, and provider-specific behavior, and includes an Agent Companion for repo-aware coding agents. Already have webhook code in an existing Rails application? The free Webhook Architecture Checkup is a repo-aware prompt for tracing the flow you already have and finding the important gaps. Webhook endpoints always seem simple when you build the first version. Add a route, create a controller action, parse some JSON, update a record and return 200 . Pretty standard Rails stuff. Then the real requirements start showing up. You need to verify that Stripe or GitHub actually sent the request. The provider wants a response quickly, so the useful work moves into a background job. The same event arrives twice. A worker dies after doing half of the work. Two related events get processed at the same time. Another event shows up out of order. At some point, that little controller action has picked up a surprising amount of infrastructure around it. Nobody starts by saying, "I need a distributed system for this webhook." You normally get there one completely reasonable requirement at a time. It is still a small system, of course. We are not building Kafka and twelve services here. But once a webhook is production-ready, you have an external trust boundary, durable ingress, asynchronous workers, duplicate delivery, retries, concurrency, ordering problems and a handful of failure states that all need to agree with each other. That is the part of webhooks I find interesting. A tiny HTTP endpoint becomes a pretty good microcosm of a much larger distributed system. First, can you trust the request? A webhook is public ingress into your application, so before doing anything useful with the payload, you need to answer the obvious security question: did the provider actually send this? Most providers solve this with a shared secret and a s