Webhook testing: local, staging, and production checks

Webhook testing should verify transport, authentication, payload handling, retry safety, and business outcomes. A single successful curl request covers only the route and parser.

Test layers

Layer	What to test
Unit	Signature helpers, schema validation, event routing, and idempotency functions.
Contract	Representative provider headers and payload fixtures.
Integration	HTTP route, raw-body middleware, database, and queue handoff.
Provider sandbox	A real delivery from the provider test environment.
Failure injection	Timeouts, duplicate events, invalid signatures, and dependency failures.

Send a basic test request

bash

curl --request POST 'https://example.com/webhooks/test' \
  --header 'content-type: application/json' \
  --header 'x-test-event-id: evt_test_123' \
  --data '{"type":"example.created","data":{"id":"obj_123"}}'

Production-ready test cases

Valid signature and expected event type.
Invalid or missing signature.
Malformed JSON and unexpected content type.
Unknown event type and missing optional fields.
Repeated delivery of the same event ID.
Slow downstream dependency and queue outage.
Payload at the documented size boundary.

Testing procedure

Create a dedicated test endpoint and use non-production credentials and data.
Capture the request so you can compare the sender record with received bytes.
Assert the HTTP response and the resulting database, queue, or application state.
Run duplicate and timeout cases before enabling production delivery.
Repeat provider sandbox tests after middleware, proxy, secret, or schema changes.

Exit criteria

Valid requests are accepted and invalid requests are rejected for the expected reason.
Acknowledgment meets the provider timeout requirement.
Duplicate events do not duplicate side effects.
Logs contain an event or delivery ID without exposing secrets.