Testing Webhooks

Test webhook delivery and verification in sandbox and local development.

Placeholder webhook contract

Event names, signature headers, and payload fields are illustrative until the finalized webhook specification is published.

Prove delivery, signature verification, and idempotency in sandbox before you rely on webhooks in production.

Sandbox setup

Register a public HTTPS URL (or tunnel) in the sandbox project under Project Settings → Webhooks.
Store the sandbox signing secret as WEBHOOK_SECRET — verify signatures from day one, even in tests.
Trigger test events and inspect recent deliveries, response codes, and retry history in the dashboard.

Use the dashboard's "Send test event" action if your sandbox offers it (illustrative).
Otherwise complete a sandbox payment and watch your endpoint receive the real deliveries.

Test the failure path

Deliberately return 500 once, then confirm the retry arrives with the same event id.

Expose localhost with a tunnel, then use the public HTTPS URL as your endpoint:

ngrok http 8080
# use the https://*.ngrok-free.app URL as your webhook endpoint

Every request verified with X-HellOOpass-Signature using constant-time comparison.
Events deduplicated by event id with a unique constraint.
2xx returned only after durable persistence; heavy work runs in the background.
5xx returned when persistence fails, so delivery is retried.
Dead-letter queue and alerts exist for poison events and delivery failures.
WEBHOOK_SECRET stored securely and never logged.