Signature & Security
All partner-provided settlement webhooks and confirm-settlement requests are secured with HMAC-SHA256 signatures. This page covers the signing model, header requirements, and verification logic.
HMAC Signing Model
A shared secret is configured per partner during onboarding. Every webhook event sent by Settle and every confirm-settlement request sent by the partner must include a valid HMAC signature.
Signature Formula
Signature = HMAC_SHA256(secret, timestamp + rawBody)Required Headers
| Header | Description | Required |
|---|---|---|
X-Timestamp | Unix timestamp (seconds) when the request was created | Yes |
X-Signature | HMAC-SHA256 signature of timestamp + raw request body | Yes |
X-Event-Id | Unique event identifier (outbound events from Settle only) | Outbound only |
Important: The shared secret is provided during partner onboarding. Keep it secure and never expose it in client-side code.
Validation Rules
Both Settle (when receiving confirm-settlement requests) and your server (when receiving webhook events) should follow these validation rules:
Reject stale requests
If the X-Timestamp is older than 5 minutes from the current server time, reject the request.
Validate signature
Recompute the HMAC using your shared secret, the timestamp, and the raw body. Compare it with the X-Signature header using a timing-safe comparison.
Ensure idempotency
Use the settlementId or X-Event-Id to deduplicate requests. Store processed IDs and skip duplicates.
Tip: Always process events asynchronously. Return 200 immediately and handle business logic in a background job to avoid webhook timeouts.