What Is a Webhook?

A webhook has two sides. The sender is a system where things happen: a payment clears, a branch gets pushed, a ticket changes owner. The receiver is an HTTPS endpoint you control and hand to the sender in advance. Nothing travels between them until the event occurs. Then the sender makes one HTTP POST to your URL with a body describing what changed.

Here is what a real delivery looks like on the wire. This is a trimmed Stripepayment_intent.succeeded event, the single most common webhook in production software:

Three fields do most of the work. id gives you a deduplication key. type tells your router which handler to call. created lets you reject deliveries that have been sitting in someone else’s replay buffer.

An API and a webhook are both HTTP. The difference is who starts the conversation. With an API, your code asks a question and waits for an answer, so freshness costs you a request every time you check. With a webhook, the other system speaks first, and you only spend resources when something actually changed.

The last row matters more than it looks. Payloads are snapshots, and a snapshot can be stale by the time your queue gets to it. For anything financial or irreversible, treat the webhook as a notification and read the authoritative value back from the API.

Stripe emits several hundred event types. Teams subscribe to a handful: payment_intent.succeeded to fulfil an order, invoice.payment_failed to start dunning, charge.dispute.created to freeze an account before the chargeback lands. Stripe retries failed deliveries with exponential backoff for up to three days.

GitHub fires push, pull_request, and workflow_run events at any URL you register on a repository or organisation. Almost every deploy bot, Slack notifier, and third-party CI runner is built on these. GitHub expects your endpoint to answer within ten seconds and does not retry automatically, though every delivery is stored and can be replayed by hand from the repository settings.

Slack delivers workspace activity through its Events API: app_mention when someone tags your bot, message.channels for channel traffic. Slack wants an acknowledgement within three seconds and retries three times if it does not get one, which is why every Slack bot answers immediately and posts its real reply afterwards.

Twilio is the useful odd one out. An inbound SMS arrives as application/x-www-form-urlencoded rather than JSON, with fields named From, To, and Body, and Twilio reads your response body as instructions for what to do next. Not every webhook is JSON, and not every webhook ignores what you send back.

Senders sign each delivery with an HMAC computed over the raw request body and a shared secret. Your job is to recompute that HMAC and compare. Three details cause nearly every failed integration and nearly every vulnerability.

First, sign the bytes you received. Frameworks that parse JSON before your handler runs will quietly break verification, so configure a raw-body parser on the webhook route only. Second, bound the timestamp. Without a tolerance window, a signature captured today stays valid forever and a replayed delivery is indistinguishable from a real one. Third, compare in constant time.

Beyond the signature: accept HTTPS only, keep two secrets valid during rotation so you can roll without dropping deliveries, and scope the endpoint so it can do nothing except enqueue work. IP allowlisting sounds appealing and ages badly, since provider egress ranges change without much notice.

The pattern that has become standard for production agents is short: an event fires, an agent runs, the result goes back where the work lives. A ticket lands in Zendesk and an agent drafts the reply. An invoice hits an inbox and an agent extracts the line items into the ERP. A deal moves stage in the CRM and an agent assembles the handover brief. In each case the webhook is what turns a passive assistant into something that acts on its own schedule.

The operational shape differs from a normal webhook handler in one way: agent runs take seconds to minutes, far longer than any sender will wait. Acknowledge the delivery immediately, run the agent asynchronously, and write results back through the source system’s API.

In Swfte Studio a workflow can start from a webhook trigger without you standing up a server, and the model calls inside that workflow run through Connect, which fronts 50+ providers behind one API with automatic failover and per-call cost tracking. That matters for event-driven work specifically: a webhook keeps arriving whether or not your primary model provider is having a good day.

Timeouts. The usual cause is doing the work inside the request. Signature check, enqueue, return 200. Anything slower than about a second belongs on a queue, and a handler that calls three internal services before responding will eventually cross whatever limit the sender enforces.

Duplicates. Retries mean at-least-once delivery, so the same event id will arrive twice sooner or later. Deduplicate on the event id with a unique constraint rather than a cache lookup, because two retries can land on two instances at the same moment:

Out-of-order arrival. Parallel delivery workers mean subscription.updated can arrive before the subscription.created that caused it. Never trust arrival order. Sort on a field inside the payload, usually the object’s own version counter or updated timestamp, and drop anything older than what you have already applied.

Silent failures. A webhook that stops arriving looks exactly like a quiet week. Alert on the absence of expected events, keep the sender’s delivery log open when debugging, and log the event id on both sides so a support conversation can start from a shared identifier. Our error encyclopedia and fix guides cover the specific HTTP and TLS failures that show up in delivery logs.