Skip to main content

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.
X-Message-Signature is not sent in this format. Integrations that verify it must move to Webhook-Signature. The format is live in sandbox; production switches on a date Trace Finance announces. See Migrating from the previous 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:
Verify against the raw body bytes exactly as received. Do not parse and re-serialize the JSON before verifying: any change in whitespace or key order invalidates the signature.

Verification steps

  1. Read Webhook-Id, Webhook-Timestamp and Webhook-Signature from the request headers. Header names are case-insensitive and most frameworks lowercase them, so look them up without regard to case.
  2. Reject the request if Webhook-Timestamp differs from your current time by more than a tolerance (5 minutes is recommended). This blocks replay of captured requests.
  3. Compute the expected signature over {Webhook-Id}.{Webhook-Timestamp}.{raw body} with your client secret.
  4. Split Webhook-Signature on spaces. Accept the request if any entry starting with v1, 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 form whsec_ followed by the Base64 encoding of your client secret:

Verify manually

If you prefer not to add a dependency, implement the steps yourself.
Always compare signatures in constant time (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 and Webhook-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

Your clientId 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.
If you suspect your client secret has been compromised, rotate it immediately and re-verify previously stored event IDs to detect any spoofed deliveries.