Webhook Delivery Service  ·  View 04 of 20  ·  People and journeys

Journey — First Webhook

An integration developer, one afternoon, and the phase where it always goes wrong.

Editable source SVG draw.io All views
Integration Developer first integration Goal — Get a signed event arriving in my staging service this afternoon Trigger — A feature needs to react to payments in near-real time Done when — Events arriving, verified, and a page that proves it 1 · Register console or API 2 · Verify ◆ moment of truth 3 · First event 4 · First failure ◆ moment of truth 5 · Go live What they do Creates an endpoint Picks event types Copies the secret Writes verification Fires a test event Opens the attempt log Enables in production How it feels Confident Fine Stuck Where it hurts Signature will not match No reason given Their 4xx looks like ours What the platform gives Validation challenge Canonical string, published Verify examples Request inspector Outcome class + reason Delivery health API Journey — Integration Developer, First Webhook The trough is verification. It is the one phase where the platform's documentation is the product. v 1.0 · owner Integration Platform Architecture · date 2026-09

The trough is verification

  • Every webhook platform's support load concentrates in one place: a developer whose recomputed signature does not match and who has no way to find out why.
  • The causes are always the same — the body was re-serialised by a framework before they hashed it, or the timestamp was not in the signed material, or they used the wrong secret during a rotation.
  • The architectural answer is not a better error message. It is a published canonical string, the raw bytes available in the request inspector, and worked verification examples in the languages the customer base actually uses (ADR-06).

Design consequences

  • An endpoint that has never once succeeded is never enabled. The validation challenge in phase 2 is a requirement, not onboarding polish.
  • The fourth phase — first failure — is marked as a moment because a 4xx classified as permanent stops retries immediately. If the developer cannot tell their 4xx from the platform's, they lose events and blame the platform.

Assumptions

  • Verification examples in six languages is a stated assumption; the real number is whatever covers 90% of the customer base's stacks.
  • The whole journey fitting in an afternoon is the target this platform is designed against, not a measurement.
◀  Actors and Their Journeys All views Journey — Endpoint Outage  ▶
Solution Architecture v1.0 · Amazon Web Services · Integration Platform Architecture · 2026-09 · 20 views · 16 architecture decision records04-journey-integrate-endpoint