Retries & Replays
The webhook dispatcher retries on transient failures and gives up on permanent ones. This page covers the exact behaviour so your endpoint can plan for it.
Retry schedule
Total retry window: ~6 minutes. After that the event is marked
gave_up in our audit log and no further attempts are made.
What triggers a retry
Why 4xx doesn't retry
Most 4xx responses indicate your endpoint is broken in a way time won't fix:
- 401/403 — wrong shared secret
- 404 — endpoint doesn't exist
- 405 — wrong HTTP method
- 422 — payload schema mismatch
If your endpoint needs time to recover (e.g. you just deployed +
the route 404s for 30 seconds), respond with 503 instead of 404
during the deploy window. We'll retry.
Idempotency
Every webhook attempt carries a unique X-Splashify-Delivery-ID
header. Even retries of the same event have a fresh delivery ID.
To dedup at your end, key off mail.messageId + eventType:
const key = `${body.mail.messageId}:${body.eventType}`;
const inserted = await db.events.insertOne({
_id: key,
...body,
receivedAt: new Date(),
}, { ignoreDuplicates: true });
if (!inserted.insertedCount) {
return res.status(200).end(); // already processed, ack
}
// ... processEven if we retry due to your 500 response, the second delivery has
the same mail.messageId + eventType and your insert dedups it.
Open, Click and DeliveryDelay can fire more than once for one
email. To keep each of those, add mail.timestamp to the key: it stays
the same across retries of one event and differs between events.
Manual replay
For events that gave up (your endpoint was down for >6 minutes), contact support to replay them. We retain the full event log for 30 days and can re-fan-out a specific window.
Self-serve replay is on the roadmap — POST /partner/email/events/replay
with a time range + optional event-type filter.
Finding events a webhook missed
GET /events lists what happened to your sends on one day, so you
can compare it with what your endpoint received:
curl 'https://api.splashifypro.com/api/v1/partner/email/events?day_bucket=2026-05-03' \
-H "Authorization: Bearer $SPLASHIFY_API_KEY"It lists the events, not the delivery attempts: per-destination delivery status is not in the API yet.
Common reasons for repeated failures
- Endpoint times out > 10 seconds. Your handler should ack ASAP (write to a queue, return 200) and process async.
- Endpoint behind Cloudflare with bot protection. Bot challenges
return 403 to our requests — whitelist our user-agent
(
Splashify-Pro-Webhook/1.0) or our outbound IP range. - HTTPS cert expired. We don't disable cert verification. Renew + monitor.
- Wrong secret. If you rotated the secret in the panel but didn't roll it on your endpoint, every signature check returns 401.