Webhooks salientes

Mosend dispara webhooks HTTP POST hacia tu URL cada vez que ocurre un evento relevante. Los gestionas desde el dashboard (Configuración → Integraciones → Webhooks) o vía API.

Firma HMAC

Cada request lleva el header X-Mosend-Signature con HMAC SHA-256 del body crudo, usando el secreto que recibiste al crear el webhook. Tu endpoint debe validarlo antes de procesar el evento.

# Node.js — validación del HMAC
import crypto from 'node:crypto';

function verify(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Estructura del payload

{
  "event": "message.new",
  "deliveryId": "0d6f2c9e-...",
  "organizationId": "a1b2c3d4-...",
  "occurredAt": "2026-05-01T03:42:18.123Z",
  "data": {
    "conversationId": "...",
    "message": { "id": "...", "direction": "IN", "type": "text", "payload": {...}, ... }
  }
}

Tu endpoint debe responder 2xx en menos de 10 s. Si falla, Mosend reintenta con backoff exponencial hasta 8 veces (≈30 minutos). Después marca el delivery como FAILED y queda en el log.

Eventos disponibles

Evento	Cuándo se dispara
message.new	Llega un mensaje entrante o se envía uno saliente confirmado por Meta.
message.status	Cambio de estado de un mensaje saliente (sent → delivered → read, o failed).
conversation.opened	Se abre una nueva conversación.
conversation.closed	Se cierra una conversación manualmente.
conversation.assigned	Se asigna o reasigna a un agente.
template.status	Cambio de estado de plantilla (PENDING → APPROVED/REJECTED) por webhook de Meta.
phone.quality	Cambio del quality rating del número (GREEN/YELLOW/RED).
invoice.issued	Cierre de período facturado y emisión de factura.
invoice.paid	Pago confirmado de factura.
invoice.overdue	Factura cruzó la fecha de vencimiento sin pagar.
wallet.recharged	Recarga de saldo confirmada por Mercado Pago.

Idempotencia

Cada delivery tiene un deliveryId único. Si recibes el mismo deliveryId dos veces (porque el primero falló pero igual fue procesado por tu lado), debes deduplicar. Mosend reintenta cualquier delivery que no haya recibido respuesta 2xx.