Project: webhook contract and browser verification

Last updated: 5 Oct 20268 min read

project

Build a small media-processing callback for case 47. The external processor sends an event when image 61 is ready. Verify the event's raw-body signature and freshness, record its event ID before applying a side effect, then expose the resulting image state through an API shape that an older browser client can still read. A critical browser journey opens the case URL directly and checks the visible result after a refresh. The deliverable is a running boundary trace: accepted event, duplicate event, altered payload, stale event, old client, and direct-route browser load.

Build contract

Verify the exact raw bytes and timestamp with a configured signing key; keep the key out of client bundles and logs.
Use a uniqueness constraint on event ID and a short acknowledgement path, moving longer conversion work to a durable queue.
Retain the old response field during a measured compatibility window, then test old and new browser clients against the intermediate shape.

Implementation checkpoint

INSERT INTO received_events (event_id, event_type, received_at)
VALUES (:event_id, :event_type, CURRENT_TIMESTAMP)
ON CONFLICT (event_id) DO NOTHING;

Cost and boundaries

Signature verification scans the body, O(B), and event-ID retention uses storage proportional to the accepted delivery window. Browser journeys cost more than unit tests because they start the built application and real page logic. Keep a short critical route test in the release gate and use field performance evidence to check whether the image change helped real devices.

Acceptance checks

Send the same signed event twice; the second acknowledgement must not create a second image state.
Change one payload byte and move the event timestamp outside the allowed window in separate tests.
Run an old client against the expanded API, then open the case route directly in the built release.

Common Mistakes

Reconstructing JSON before signature verification.
Assuming a successful component test proves the deployed nested route works.
Removing an old API field while cached browser clients still depend on it.

web-tech

web-development