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)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Con el SDK de TypeScript no escribís el HMAC a mano: parseWebhookEvent valida la firma (timing-safe) y te devuelve el evento tipado como unión discriminada.

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.event → 'message.new' | 'message.status' | ...
  // deduplicá por event.deliveryId (puede reintentarse)
} catch (err) {
  if (err instanceof MosendWebhookSignatureError) return res.sendStatus(401);
  throw err;
}

Estructura del payload

El cuerpo es JSON con type (el evento), organizationId, data (el recurso) 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-...",
  "data": {
    "conversationId": "...",
    "message": { "id": "...", "direction": "IN", "type": "text", "payload": {...}, ... }
  },
  "timestamp": "2026-05-01T03:42:18.123Z"
}

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

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 (ej. un bot externo que opera un único WhatsApp), pasá 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 (la mayoría: message.*, conversation.*) → entrega solo si está en la lista permitida.
• No trae número pero sí wabaId (template.status) → entrega si la WABA tiene al menos un número permitido.
• Eventos globales de la org sin número ni WABA (facturación, uso, etc.) → 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.

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.message.id para message.new / message.status, o data.conversationId para los eventos de conversación.