Webhooks salientes

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)          // body CRUDO: el mismo byte a byte que llegó
    .digest('hex');
  const a = Buffer.from(signature ?? '');
  const b = Buffer.from(expected);
  // timingSafeEqual lanza si los largos difieren: compáralos antes.
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

Con el SDK de TypeScript no escribes el HMAC a mano: parseWebhookEvent valida la firma (timing-safe) y te devuelve el evento tipado.

import { parseWebhookEvent, MosendWebhookSignatureError } from '@moshipp/mosend-sdk';

// body = Buffer/string CRUDO del request (sin parsear)
try {
  const event = parseWebhookEvent(
    body,
    req.header('X-Mosend-Signature'),
    process.env.MOSEND_WEBHOOK_SECRET,
  );
  // event.type → 'message.new' | 'message.status' | ...
} catch (err) {
  if (err instanceof MosendWebhookSignatureError) return res.sendStatus(401);
  throw err;
}

Estructura del payload

Todos los eventos llegan con el mismo sobre: type (el evento), organizationId, data (el contenido) y timestamp. El tipo de evento también viaja en el header X-Mosend-Event, y la firma en X-Mosend-Signature.

POST tu-url
X-Mosend-Event: message.new
X-Mosend-Signature: sha256=<hmac-del-body-crudo>
Content-Type: application/json

{
  "type": "message.new",
  "organizationId": "a1b2c3d4-...",
  "timestamp": "2026-09-17T03:42:18.123Z",
  "data": {
    "conversationId": "...",
    "phoneNumberId": "...",
    "messageId": "...",
    "direction": "IN",
    "messageType": "text",
    "text": "Hola, ¿tienen stock?",
    "contactWaId": "573001234567",
    "contactName": "Ana",
    "receivedAt": "2026-09-17T03:42:17.900Z"
  }
}

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.

Nombres antiguos que siguen funcionando

Versiones anteriores de esta página y del SDK listaban eventos que el backend nunca emitió. Si tu webhook está suscrito con uno de esos nombres, lo aceptamos como alias del evento real — no hace falta que cambies nada, aunque el body llega con el nombre real en type:

• conversation.assigned → conversation.assignment_changed
• phone.quality → quality.changed

conversation.opened y conversation.updated no tienen equivalente: no existe un webhook de apertura ni uno genérico de cambio. Para saber que una conversación empezó, usa message.new con direction: "IN"; para los cambios de estado, conversation.closed, conversation.assignment_changed y conversation.handoff_requested.

Restringir por número (phoneNumberIds)

Por defecto un webhook recibe eventos de todos los números de la org. Si tu integración solo debe enterarse de un número (por ejemplo, un bot externo que opera un único WhatsApp), pasa phoneNumberIds al crear o editar el webhook con los UUID de Mosend de los números permitidos. Vacío o ausente = todos.

# Crear un webhook acotado a un solo número
curl -X POST 'https://api.mosend.dev/organizations/{orgId}/webhooks-outbound' \
  -H 'X-Api-Key: mk_live_<prefix>.<secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://tu-app.com/webhooks/mosend",
    "events": ["message.new", "message.status", "conversation.handoff_requested"],
    "phoneNumberIds": ["<UUID-del-numero>"]
  }'

Cómo decide Mosend si entregar a un webhook con scope:

• El payload trae phoneNumberId (mensajes, conversaciones, canales, citas, ventas) → entrega solo si está en la lista permitida.
• No trae número pero sí wabaId (template.status) → entrega si esa cuenta de WhatsApp tiene al menos un número permitido.
• Eventos de la organización sin número ni cuenta (agent.status_changed, facturación, uso, prueba) → no se entregan a webhooks con scope. Para recibirlos, deja un webhook sin phoneNumberIds.

Umbral de conversation.unanswered

Si te suscribes a conversation.unanswered, puedes ajustar cuántos minutos espera Mosend antes de avisarte con unansweredThresholdMinutes (1–1440, default 2). Solo cuenta como "respondido" un mensaje de un asesor humano — el bot IA, las auto-respuestas y las plantillas no cierran el reloj. Se emite una sola notificación por mensaje sin responder, y solo para conversaciones OPEN.

Filtrar agent.status_changed por estado

Con agentStatuses eliges qué estados de jornada disparan el evento: ONLINE, LUNCH, BREAK, MEETING, TRAINING, ENDED. Vacío o ausente = todos.

Idempotencia

Mosend reintenta cualquier entrega que no reciba un 2xx, así que tu endpoint puede recibir el mismo evento más de una vez. El payload no incluye un id de entrega: deduplica por el id del recurso dentro de data — por ejemplo data.messageId para message.new y message.status, data.conversationId para los de conversación, o data.invoiceId para los de facturación.

Formato Microsoft Teams

Si el destino es un canal de Teams, crea el webhook con format: "TEAMS" (o deja que Mosend lo detecte por la URL): el evento se convierte en una Adaptive Card que Teams sí renderiza. En ese formato no se mandan X-Mosend-Signature ni X-Mosend-Event, porque Teams ignora las cabeceras propias. Para tu propio servidor usa format: "GENERIC", que es el JSON descrito arriba.