Retry behavior and idempotency
3 min read Updated October 22, 2026
Delivery and retries
A delivery times out after 10 seconds. A network error or a 5xx response is retried twice, after 1 second and then 4 seconds. A 4xx response, or a redirect, is not retried. After the last attempt the delivery is recorded as failed; there is no automatic long-term retry schedule.
Be idempotent
Duplicates are possible, so processing an event twice must be harmless. Use the delivery ID (X-ComplianceGrid-Delivery, or the event id) to deduplicate:
javascript
const seen = new Set(); // use Redis or a database in production
app.post('/webhooks/compliancegrid', (req, res) => {
const id = req.headers['x-compliancegrid-delivery'];
if (seen.has(id)) return res.status(200).json({ received: true, duplicate: true });
seen.add(id);
handleEvent(req.body);
res.status(200).json({ received: true });
});If you miss events
Watchlist events can be read back through the monitoring API (GET /v1/monitoring/watchlists/{id}/events), and a batch job's results through GET /v1/risk/batch/{jobId}/results, so a failed delivery never loses the data.
Practice
- Answer 200 quickly and process asynchronously
- Log delivery IDs
- Return 200 for event types you do not handle
Was this article helpful?