MailingCore
DocumentazioneConsegne e retry

Consegne e retry

Log consegne, policy retry BullMQ e gestione idempotente.

Ogni webhook in uscita viene persistito e consegnato in modo asincrono tramite la coda BullMQ mc:webhook-delivery. Usa l'API consegne per debuggare i fallimenti e progettare receiver idempotenti.

Log consegne

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

Ogni record WebhookDelivery include:

CampoSignificato
idID consegna (anche in X-MailingCore-Delivery-Id)
eventTipo evento (email.bounced, contact.unsubscribed, …)
payloadCorpo JSON consegnato al tuo URL
statusCodeHTTP status dal tuo server (se c'è stata risposta)
responseBodyCorpo risposta troncato per debug
attemptNumero tentativo (1–5)
deliveredAtTimestamp dell'ultimo tentativo
createdAtQuando la consegna è stata accodata

Il limit predefinito è 20 se omesso.

Policy di retry

ImpostazioneValore
Codamc:webhook-delivery
Tentativi max5
BackoffEsponenziale, delay base 10 s
Timeout richiesta10 s per chiamata HTTP
Criterio successoRisposta HTTP 2xx

In caso di status non-2xx o errore rete/timeout, BullMQ riaccoda il job con backoff esponenziale fino ad esaurire i tentativi. Dopo il quinto fallimento, la consegna resta con l'ultimo statusCode e non ci sono altri retry automatici per quel job.

POST https://tua-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...

Checklist receiver

  1. Rispondi velocemente

    Restituisci 200 entro pochi secondi. Il lavoro pesante va nella tua coda.

  2. Verifica firma

    Valida X-MailingCore-Signature sul raw body prima di parsare JSON — vedi Verificare firma.

  3. Deduplica

    Usa X-MailingCore-Delivery-Id o il campo id del payload. I retry possono ripetere lo stesso evento logico.

  4. Monitora fallimenti

    Interroga GET /webhooks/endpoints/:id/deliveries o allerta su statusCode non-2xx ripetuti.

Correlati