MailingCore
DocumentacionEntregas y reintentos

Entregas y reintentos

Log de entregas, politica de retry BullMQ y manejo idempotente.

Cada webhook saliente se persiste y entrega de forma asincrona via la cola BullMQ mc:webhook-delivery. Usa la API de entregas para depurar fallos y disenar receptores idempotentes.

Log de entregas

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

Cada registro WebhookDelivery incluye:

CampoSignificado
idID de entrega (tambien en X-MailingCore-Delivery-Id)
eventTipo de evento (email.bounced, contact.unsubscribed, …)
payloadCuerpo JSON entregado a tu URL
statusCodeHTTP status de tu servidor (si hubo respuesta)
responseBodyCuerpo de respuesta truncado para depuracion
attemptNumero de intento (1–5)
deliveredAtTimestamp del ultimo intento
createdAtCuando se encolo la entrega

El limit por defecto es 20 si se omite.

Politica de reintentos

AjusteValor
Colamc:webhook-delivery
Intentos max5
BackoffExponencial, delay base 10 s
Timeout peticion10 s por llamada HTTP
Criterio exitoRespuesta HTTP 2xx

Ante status no-2xx o error de red/timeout, BullMQ reencola el job con backoff exponencial hasta agotar intentos. Tras el quinto fallo, la entrega queda con el ultimo statusCode y no hay mas reintentos automaticos para ese job.

POST https://tu-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 del receptor

  1. Responder rapido

    Devuelve 200 en pocos segundos. El trabajo pesado va en tu propia cola.

  2. Verificar firma

    Valida X-MailingCore-Signature sobre el raw body antes de parsear JSON — ver Verificar firma.

  3. Deduplicar

    Usa X-MailingCore-Delivery-Id o el campo id del payload. Los reintentos pueden repetir el mismo evento logico.

  4. Monitorizar fallos

    Consulta GET /webhooks/endpoints/:id/deliveries o alerta ante statusCode no-2xx repetidos.

Relacionado