Class 87 gave you a memory of the customer — tickets, CRM context, follow-up. Now the business grows and the manual copy-paste breaks: someone pays, and somebody has to create the account, send the receipt, and update the CRM before morning. Webhooks are how systems tap each other on the shoulder and say "this really happened." Get this right and your operation runs while you sleep; get it wrong and you grant access to people who never paid.

The vocabulary, in plain language

• Event: something that happened that other systems may care about — "checkout completed," "subscription cancelled." A fact, with a timestamp.
• Webhook: an automatic HTTP message one system sends to another when an event happens. Instead of asking "anything new?" every minute, you get knocked on the door when there is news.
• Payload: the contents of that knock — structured data describing the event: who, what, how much, which IDs.
• Endpoint: your URL that receives the knock — the door. Example: https://yourapp.com/webhooks/stripe.
• Signature: the proof the knock is genuine. The sender signs the payload with a secret only you two share; you check the signature before acting. No signature check, no action.
• Retry: the sender trying again when your door doesn't answer. Networks fail; retries make delivery reliable.
• Idempotency: safe to receive twice. Because retries happen, your handler must produce the same result whether it sees the event once or three times — check "have I already processed event ID ___?" before acting.
• Error queue: the parking lot for messages that couldn't be processed — malformed, unverifiable, or repeatedly failing. A human reviews them instead of them vanishing.

The mental model: a webhook is registered mail, not a shouted rumor. Registered mail has a sender ID (signature), a tracking number (event ID for idempotency), redelivery attempts (retries), and a dead-letter office (error queue) when delivery truly fails.

The canonical example: checkout to access

Follow one ByeBuy-style purchase, step by step:

checkout → verified event → grant access → send confirmation → update CRM

1. Customer completes checkout with the payment provider. 2. The provider sends a checkout.session.completed webhook to your endpoint — with payload and signature. 3. You verify the signature first. Only then do you trust it. 4. You check idempotency: "have I processed this event ID before?" If yes, acknowledge and stop. 5. Side effects, in order: grant access (create account/entitlement), send confirmation (receipt email), update CRM (lifecycle stage → customer, per Lesson 87.4). 6. You log everything: event ID, time, verification result, actions taken. 7. Failures go to the error queue with the reason — never silently dropped.

Contrast this with browser text: a redirect, a query parameter, or front-end JavaScript saying "payment succeeded!" The browser belongs to the customer — it can be edited, replayed, or faked. Never grant access on browser text. Grant access only on a signature-verified event received server-side. This single rule prevents the most common automation fraud: free access from a forged success page.

For the authoritative reference on this pattern, read Stripe webhooks — it covers signatures, retries, idempotency, and local testing better than any summary.

What your endpoint must do, every time

A minimal safe receiver follows this order — no shortcuts:

1. Receive — accept the POST, store the raw body before parsing (signatures are computed on raw bytes). 2. Verify — check the signature with the stored secret. Fail → log, return 400, no side effects. 3. Deduplicate — look up the event ID. Seen → return 200, do nothing more. 4. Validate — is the payload well-formed and the type one you handle? Unknown types → log and acknowledge (don't crash); malformed → error queue. 5. Act — perform the bounded side effects from the contract (Lesson 84.3). 6. Log — event ID, type, verification, actions, duration. This log is what Lessons 88.4 and 88.5 review.

Return 200 quickly. Long work (emails, provisioning) belongs in a background job triggered by the verified event — not inside the webhook handler where timeouts cause duplicate retries.

Exercise: map your event flow

Create EVENT-FLOW.md:

# EVENT-FLOW.md — [Workflow, e.g. Purchase → Access]

## Trigger event
- Provider + event type: ___ (e.g. Stripe `checkout.session.completed`)
- Reference: [Stripe webhooks](https://docs.stripe.com/webhooks)

## Receiver
- Endpoint URL: ___ (server-side only; never browser text)
- Secret location: ___ (secret manager — see Lesson 88.3)

## Verification
- Signature check: ___ (how — library/function name)
- On failure: log + return 400 + no side effects

## Side effects (in order, each idempotent)
1. ___ (e.g. grant access — check existing entitlement first)
2. ___ (e.g. send confirmation)
3. ___ (e.g. update CRM stage)

## Idempotency
- Event-ID store: ___ / lookup before acting

## Retry + error queue
- Retry handling: acknowledge fast; background job for slow work
- Error queue location + reviewer + cadence: ___

## Log (every delivery)
- event ID / type / time / verification / actions / outcome

Worked mini-example — local service booking deposit: event payment.succeeded → verify signature → idempotency check on payment ID → mark booking confirmed → send confirmation SMS → update CRM to "booked." A customer showing a "success!" screenshot gets a smile and a "let me check the verified event" — access follows the webhook, never the screenshot.

Finish line: an EVENT-FLOW.md with a named event, a server-side endpoint, explicit signature verification, ordered idempotent side effects, and a retry/error-queue plan.

Verify quickly: send yourself three test deliveries — a valid event, the same event twice, and a forged event with a bad signature. Valid grants access once; the duplicate does nothing; the forgery does nothing and gets logged.

Common failure mode: acting on unverified input — granting access from a URL parameter or a front-end callback, or processing the same event twice and double-provisioning. Both are prevented by the two lines builders skip: verify, then deduplicate.

Check your understanding

1. Why must access follow a verified webhook rather than browser text? 2. What does idempotency protect against, and where do retries come from? 3. What belongs in the error queue, and what must never vanish silently?

Next

Events arrive safely. Now where does the workflow live — a visual platform, a connector, or your own code? Lesson 88.2 compares n8n, Make, Zapier, and custom code so you pick the right home for this flow.