Retries & dead-letter queue

What we consider success

Any HTTP 2xx response within 10 seconds. Anything else (3xx, 4xx, 5xx, network error, timeout) is a delivery failure and triggers a retry.

Retry schedule

Dead-letter queue

After the 6th failed attempt, the delivery is moved to our DLQ and marked status: gave_up in the deliveries table. We do not auto-retry from the DLQ — but you can replay them.

# List your DLQ deliveries
curl 'https://api.aiactradar.com/v1/deliveries?status=gave_up' \
  -H "Authorization: Bearer $AIACTRADAR_API_KEY"

# (Replay endpoint coming in v1.1)

Idempotency

The same event.id may arrive multiple times across retries (and even on the first attempt if your endpoint times out after a partial response). Use delivery.id to deduplicate per-attempt, and event.id for end-to-end deduplication.

What kills your delivery rate

• Returning 200 but actually failing your downstream (we retry only if status is non-2xx — silent failures are on you)
• Cold-start timeouts on serverless receivers — process async if your handler may exceed 10 s
• Strict CSP / firewall blocking our User-Agent AIActRadar-Webhook/1.0
• Cloudflare / Vercel / Netlify rate-limits on your side blocking burst-deliveries

Disabling deliveries

If you need to pause without losing the subscription:

curl -X DELETE https://api.aiactradar.com/v1/subscriptions/$SUB_ID \
  -H "Authorization: Bearer $AIACTRADAR_API_KEY"

This soft-deletes (sets enabled = 0). Re-create the subscription to resume.