Verify merchant onboarding webhooks
Keep the Sign-Up event contract separate from gateway transaction events.
Scope
This page concerns Merchant Sign-Up application notifications. Its secret and payload verification procedure are not interchangeable with payment-gateway webhook settings.
Signature calculation
The Signature header carries an HMAC-SHA256 value computed from the raw JSON event payload and subscription secret. Do not prefix the payload with the gateway nonce format. Header: Signature: <signature> Signed bytes: <unmodified JSON request body> Algorithm: HMAC-SHA256 Secret: Sign-Up webhook subscription secret
Recommended receiver design
Use a dedicated route or explicit product configuration so event families cannot accidentally share verification rules. Capture raw bytes before parsing JSON. Load the secret for this subscription and environment. Validate the signature with a constant-time comparison. Validate the parsed application event against the intended merchant workflow. Persist the accepted event and apply application transitions safely.
Delivery and recovery
The documentation describes retries after failed delivery at increasing delays and lists timeouts, connection failures and HTTP failures as triggers. HTTP 410 is excluded from retryable HTTP responses. Build a monitoring and recovery path rather than treating webhooks as an unlimited event archive.
Test independently
Recommended tests include gateway-header rejection on this route, malformed signatures, body mutation, repeated notifications and interrupted processing. Record the current application status separately from notification arrival order. The source contains an inconsistent final attempt count versus its listed initial attempt plus three retries. Do not encode an exact attempt count as a business guarantee; confirm delivery behavior during integration testing.