Verify gateway webhooks
Authenticate gateway events before they change your application state.
Register an event receiver
Create an HTTPS endpoint with valid TLS, then configure it under Merchant Portal → Settings → Webhooks and select the event types you need. Chargeback events require processor reporting support. webhook
Signing contract
The gateway sends Webhook-Signature containing t and s. Treat t as the supplied nonce. Compute HMAC-SHA256 using the gateway signing key over the nonce, a period and the original request body. Compare the computed value with s. Header: Webhook-Signature: t=<nonce>,s=<signature> Signed bytes: <nonce> + "." + <unmodified request body> Algorithm: HMAC-SHA256 Secret: gateway webhook signing key
Receiver implementation sequence
Recommended implementation controls around the documented signature contract: Read and preserve the raw request bytes before JSON middleware changes them. Require the expected header structure and reject missing or malformed components. Compute the signature with the configured gateway signing key. Use a constant-time comparison after validating signature encoding and length. Only after verification, parse the event and enforce your application validation. Deduplicate by event_id before applying a financial state transition.
Event structure
The gateway event envelope identifies an event and its category, with the category-specific content in event_body. Field Role event_id Unique event identifier. event_type Identifies the gateway event type. event_body Event-specific payload.
Receiver tests
Create local fixtures signed with a test key, then alter one body byte and verify rejection. Test an absent header, malformed components, a wrong key and a repeated event ID. These tests validate your code; delivery from an actual gateway subscription remains a separate integration test. This is the gateway signature contract. Merchant Sign-Up events use a different header and signed message. No replay-expiry interpretation of t is asserted here.