Signed-request Verification

The gateway can use request signing. Confirm the authentication mechanism that applies to your integration before exposing a public endpoint. When signing is enabled, obtain the secret through the approved setup process and verify every request before parsing or acting on it.

Verification steps

1. Capture the exact raw HTTP body before parsing or reformatting it.

2. Read the three headers and reject missing or malformed values when signing is required.

3. Remove whsec_ from the configured secret and Base64-decode the remainder.

4. Construct the signed content exactly as:

   {webhook-id}.{webhook-timestamp}.{raw HTTP request body}

5. Calculate HMAC-SHA256 with the decoded secret and Base64-encode the result.

6. Compare it against supplied v1 signatures with a constant-time comparison.

7. Reject stale timestamps (older than five minutes) and timestamps outside the permitted future clock skew.

8. Apply the agreed delivery-ID replay policy before business logic runs.

Whitespace, key order, and line breaks affect the raw body, so reconstructing JSON after parsing can invalidate a valid signature. Signing proves request authenticity and integrity; your application must still authenticate and authorise its own business operations.

Replays, retries, and operational data

Retain delivery IDs for replay handling, separately from business-operation idempotency. A repeated business action may need protection even when it uses a different delivery ID.

Keep secrets outside source code. Do not log secrets, signatures, phone numbers, or raw session IDs in unsecured logs. Use a controlled diagnostic log and internal correlation ID instead.

To confirm before publication: Document signing enablement, secure secret delivery, rotation, secret scope, unsigned-integration controls, future clock skew, delivery-ID retention, and redelivery behaviour. Publish a tested verification example and fixed non-production test vector.