Overview
Every webhook delivery follows the Standard Webhooks specification. Three headers let you verify that the request came from Trace Finance, that the body was not modified, and that the delivery is recent:
The event type, resource and customer travel in the body, under the signature. Any other header on the request, such as the tracing headers
X-Correlation-Id, traceparent and tracestate, is not signed: never trust it. See Delivery format.
Reject any request that fails verification — treat unsigned or mis-signed requests as untrusted.
What is signed
The signature covers the event ID, the timestamp and the raw request body, joined by.. The raw body is the whole JSON body, so type, resource, customerId, timestamp and data are all covered:
Verification steps
- Read
Webhook-Id,Webhook-TimestampandWebhook-Signaturefrom the request headers. Header names are case-insensitive and most frameworks lowercase them, so look them up without regard to case. - Reject the request if
Webhook-Timestampdiffers from your current time by more than a tolerance (5 minutes is recommended). This blocks replay of captured requests. - Compute the expected signature over
{Webhook-Id}.{Webhook-Timestamp}.{raw body}with your client secret. - Split
Webhook-Signatureon spaces. Accept the request if any entry starting withv1,matches the expected value, using a constant-time comparison.
Use a Standard Webhooks library
The official Standard Webhooks libraries perform every step above, including the timestamp check. They expect the secret in the formwhsec_ followed by the Base64 encoding of your client secret:
- Python
- JavaScript
- Go
Verify manually
If you prefer not to add a dependency, implement the steps yourself.- Python
- JavaScript
- Go
hmac.compare_digest, crypto.timingSafeEqual, hmac.Equal) to prevent timing attacks.
Retries and idempotency
Each retry or replay of an event keeps the same body andWebhook-Id but carries a new Webhook-Timestamp and a new Webhook-Signature, so every attempt passes the timestamp check on its own. Use Webhook-Id as your idempotency key: persist it durably and skip events you have already processed. See Retry policy.
Where to find your client secret
YourclientId and clientSecret are issued during onboarding — the same credentials used to obtain access tokens (see Authentication). Store the secret server-side; never commit it to source control or expose it in client-side code.
Related
- Retry policy — handle failed verifications without losing events
- Authentication — how
clientId/clientSecretare provisioned