Overview
When your endpoint fails to acknowledge a delivery — non-2xx response, network error, or timeout — Trace Finance records the failure and queues a retry. Every attempt is captured in an execution log you can inspect or replay manually.
What counts as success
Trace Finance considers a delivery successful when your endpoint returns any2xx status code (200, 201, 202, 204, etc.). Anything else — 4xx, 5xx, network failure, or response timeout — is recorded as FAILED and triggers retry.
Retry behaviour
Failed deliveries are queued and re-attempted after a delay. Trace Finance retries the same body with the sameWebhook-Id, letting you detect duplicates. The body is identical on every attempt, including its timestamp (when the event happened). Each attempt carries a new Webhook-Timestamp and Webhook-Signature, so a retry passes the timestamp check of signature verification on its own.
Retry counts depend on the deployed environment. Reach out to your Trace Finance contact if you need the current limit for capacity planning.
Idempotency on your side
Always treat handlers as idempotent. The sameWebhook-Id may arrive multiple times if:
- Your endpoint timed out but actually processed the event.
- A previous delivery returned
5xxand is being retried. - You manually resend a delivery.
Webhook-Id somewhere durable (a database, cache, or queue) and short-circuit duplicates before doing any side-effects.
Inspect execution logs
Every delivery attempt is recorded with the request payload, response status, and retry count.Manual replay
If your endpoint was unavailable during the original retry window, you can replay any execution log on demand. Trace Finance re-sends the same body with the sameWebhook-Id, and a new Webhook-Timestamp and Webhook-Signature.
204 No Content if the resend is queued. The replay is recorded as a new attempt in the execution log history.
Related
- Verify signatures — duplicate-safe processing depends on a correctly identified event
- Subscribe to events — pause delivery instead of returning
5xxwhen you need a maintenance window - Resend a delivery — full reference for the manual replay endpoint