MailingCore
DocumentationDeliveries and retries

Deliveries and retries

Delivery log, BullMQ retry policy, and idempotent handling.

Every outbound webhook is persisted and delivered asynchronously via the mc:webhook-delivery BullMQ queue. Use the deliveries API to debug failures and design idempotent receivers.

Delivery log

GET /webhooks/endpoints/:id/deliveries?limit=20
Authorization: Bearer mc_live_xxxx
X-Tenant-Id: clxxxxxxxx

Each WebhookDelivery record includes:

FieldMeaning
idDelivery ID (also sent as X-MailingCore-Delivery-Id)
eventEvent type (email.bounced, contact.unsubscribed, …)
payloadJSON body delivered to your URL
statusCodeHTTP status from your server (if a response was received)
responseBodyTruncated response body for debugging
attemptAttempt number (1–5)
deliveredAtTimestamp of the last attempt
createdAtWhen the delivery was enqueued

Default limit is 20 if omitted.

Retry policy

SettingValue
Queuemc:webhook-delivery
Max attempts5
BackoffExponential, 10 s base delay
Request timeout10 s per HTTP call
Success criteriaHTTP 2xx response

On non-2xx status or network/timeout error, BullMQ re-queues the job with exponential backoff until attempts are exhausted. After the fifth failed attempt, the delivery is marked with the last statusCode and no further automatic retries occur for that job.

POST https://your-app.com/webhooks/mailingcore
User-Agent: MailingCore-Webhook/1.0
Content-Type: application/json
X-MailingCore-Signature: t=1719763200,v1=...
X-MailingCore-Event: contact.unsubscribed
X-MailingCore-Delivery-Id: clxdelivery...

Receiver checklist

  1. Respond fast

    Return 200 within a few seconds. Heavy work belongs in your own queue.

  2. Verify signature

    Validate X-MailingCore-Signature on the raw body before parsing JSON — see Verify signature.

  3. Deduplicate

    Use X-MailingCore-Delivery-Id or the payload id field. Retries may deliver the same logical event more than once.

  4. Monitor failures

    Poll GET /webhooks/endpoints/:id/deliveries or alert on repeated non-2xx statusCode values.

Related