Webhooks & events

Webhooks push events to your systems as they happen — orders, publishes, deploys, and form submits — so you do not poll. This guide covers subscribing, verifying signatures, common events, and retries.

Subscribe

Open Developers Webhooks Add endpoint. Choose events and a destination HTTPS URL. Endpoints must respond within five seconds with 2xx. Use a dedicated route that verifies signatures before enqueueing work.

1. Create an endpoint URL on your server (staging first).
2. Select events you can handle idempotently.
3. Store the signing secret in your vault.
4. Send a test event from the UI and confirm receipt.

Verify signatures

Validate the signature header with your endpoint secret before processing. Reject requests that fail verification. Prefer constant-time comparison. Rotate secrets if they leak; support dual secrets briefly during rotation.

// Pseudocode
rawBody = readRequestBody()
expected = hmac_sha256(secret, timestamp + "." + rawBody)
if !secureCompare(expected, headerSignature) reject 401
if abs(now - timestamp) > 5 minutes reject 401

Always verify against the raw body, not a re-serialized JSON object. Enforce HTTPS and consider IP allowlists as defense in depth where your network model allows.

Common events

• order.completed — payment succeeded; fulfill or sync ERP
• order.refunded — restock and notify
• site.published — purge external caches, notify CMS
• deploy.succeeded / deploy.failed — CI and chat alerts
• form.submitted — CRM create / enrichment

Payloads include an id, type, createdAt, and data object. Persist the event id for idempotency.

Retries

Failed deliveries retry with exponential backoff. Make handlers idempotent using the event ID. After the retry budget exhausts, events appear in a dead-letter view for manual replay.

• Signature verification tested with a mutated payload
• Handler idempotent under double delivery
• Timeouts under 5 seconds at the HTTP layer
• Alerting on elevated failure rates

Troubleshooting

401s from your app: body altered by middleware — read raw body for HMAC.

Timeouts: move slow work to a queue; acknowledge fast.

Missing events: wrong environment subscription or filtered event types.

Prerequisites & preparation

Before changing production settings for webhooks, align the people who own content, DNS, analytics, and approvals. A fifteen-minute kickoff that names owners prevents multi-day Slack archaeology later. Capture decisions in the workspace notes so the next teammate inherits context instead of guesswork.

Gather credentials and access: workspace admin or editor role, DNS control when hostnames are involved, payment or API sandbox accounts when money paths are involved, and a shared checklist link. Confirm which environment you will rehearse in — preview first, production only after a green run.

Stand up a staging HTTPS endpoint with raw-body access for HMAC verification.

Detailed walkthrough

Work the happy path slowly the first time. Narrate what you expect to see after each click: a status badge, a DNS record, a webhook delivery, a Lighthouse metric. When reality diverges, stop and resolve the mismatch instead of clicking ahead — most outages begin as ignored yellow states.

1. Subscribe to the minimum event set you can handle idempotently.
2. Verify signatures with constant-time compare against the raw body.
3. Enqueue work and return 2xx within five seconds.
4. Persist event IDs to ignore duplicates.
5. Alert on elevated delivery failures and use dead-letter replay thoughtfully.

Edge cases & failure modes

Plan for partial failure. Networks drop, registrars delay, providers rate-limit, and humans approve the wrong revision. Your runbook should say what “abort” looks like: leave preview up, roll back the release, or freeze campaigns until metrics recover.

• Middleware parsing JSON before HMAC verification.
• Slow handlers timing out and causing retry storms.
• Subscribed to production events while pointing at a staging URL.

QA checklist before you announce

• Happy path verified on mobile and desktop
• Failure path messaging reviewed
• Owners named for the first hour after launch
• Rollback or freeze path documented

Operating the change

After launch, watch the metrics that prove the change worked — not vanity charts. Pair quantitative signals with one qualitative check (support ticket themes, sales feedback). Schedule a follow-up within a week to remove temporary flags, raise DNS TTLs, or archive the experiment.

Rotate signing secrets with dual-secret windows; review dead letters weekly.

Queues between verify and side effects keep acknowledgements fast and retries safe.

Enforce timestamp skew windows to reduce replay risk.

Idempotency is mandatory — at-least-once delivery is the normal case.

IP allowlists can complement signatures but should not replace them.

Log delivery outcomes without writing sensitive payload fields to shared sinks.

Test with a mutated signature to prove rejection before go-live.

Implementation checklist

Confirm raw-body HMAC verification on preview before you promote. Name who approves the change, which environment is authoritative, and what “done” looks like in measurable terms.

Document fast 2xx with async queues where the team already looks — workspace notes or the engineering handbook — not only in a meeting memory.

Rehearse event ID idempotency stores against written acceptance checks. If you cannot name the verification event (order, DNS lookup, deploy health, or signed API call), you are not ready to announce.

Measure timestamp skew windows with anonymized but realistic data, and keep logs, headers, or screenshots for at least one release cycle so regressions have a baseline.

Operating it with your team

Automate dual-secret rotation windows so the next teammate can repeat the path without tribal knowledge. Prefer vaulted secrets over chat paste, and archive temporary exceptions with an end date.

Review dead-letter review cadence when two tools disagree. Pick a source of truth in advance so incidents do not burn the rollback window debating dashboards.

Validate mutated signature rejection tests before paid traffic or customer emails amplify mistakes. Capture request IDs or screenshots for support if anything looks off.

When you finish this guide, you should be able to explain the happy path, the abort path, and the metrics that prove success. If any of those are fuzzy, revisit the walkthrough with your teammates before you scale traffic, spend, or automation.