Eventos de Webhooks

En la API pregunta; en el webhook Notifique avisa. Ideal para marcar campaña como entregada o medir clic en botón, sin polling.

En pocas palabras

Toda entrega es un POST application/json a la URL registrada.
Los eventos rcs.* son solo RCS; SMS usa sms.*, WhatsApp usa message.*.
instanceId trae el ID del agente RCS cuando el envío usó instancia de marca; vacío en remitente compartido.
Active solo los eventos que su integración usa.
Responda 2xx rápido; el procesamiento pesado va a cola en su lado.

Configuración general: Webhooks. Seguridad (firma HMAC): Seguridad de webhooks.

Cómo llega el POST

{
  "event": "rcs.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "inst_rcs_abc123",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "rcsId": "clxx456...",
    "to": "5511999999999",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

Campo	Descripción
`event`	Nombre del evento (ej.: `rcs.delivered`)
`workspaceId`	ID del workspace
`instanceId`	ID del agente RCS de marca, o vacío en remitente compartido
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos del envío (`rcsId`, `to`, `status`, etc.)

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id, X-Webhook-Event.

Qué debe responder su servidor

Respuesta	Efecto
2xx en hasta ~10s	Evento entregado; sale de la cola
4xx / 5xx / timeout	Reintento automático (5 min, 30 min, 2 h)

¿Procesamiento demorado? Responda 200 de inmediato y procese en segundo plano.

Referencia por evento

Evento	Cuándo dispara	Qué hacer
`rcs.sent`	RCS aceptado y enviado a la red	Marcar como enviado
`rcs.delivered`	Entregado en el dispositivo	Confirmar entrega
`rcs.clicked`	Clic en enlace corto o botón	Campaña / conversión
`rcs.failed`	Fallo (número sin RCS, instancia inactiva, etc.)	Fallback SMS o alerta
`rcs.cancelled`	Programación cancelada	Actualizar cola

Payload de cada evento

rcs.sent

{
  "event": "rcs.sent",
  "workspaceId": "clxx123...",
  "instanceId": "inst_rcs_abc123",
  "timestamp": "2025-02-10T14:29:00.000Z",
  "data": {
    "rcsId": "clxx456...",
    "to": "5511999999999",
    "status": "SENT",
    "sentAt": "2025-02-10T14:29:00.000Z",
    "messageType": "CARD",
    "payload": { "cardTitle": "Oferta" }
  }
}

rcs.delivered

{
  "event": "rcs.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "inst_rcs_abc123",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "rcsId": "clxx456...",
    "to": "5511999999999",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

rcs.clicked

Se dispara en el primer clic en enlace corto rastreado o botón de este envío.

{
  "event": "rcs.clicked",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:35:00.000Z",
  "data": {
    "rcsId": "clxx456...",
    "to": "5511999999999",
    "status": "CLICKED",
    "clickedAt": "2025-02-10T14:35:00.000Z"
  }
}

rcs.failed

Buena práctica: activar fallback (SMS, email) cuando el número no soporta RCS.

{
  "event": "rcs.failed",
  "workspaceId": "clxx123...",
  "instanceId": "inst_rcs_abc123",
  "timestamp": "2025-02-10T14:29:30.000Z",
  "data": {
    "rcsId": "clxx456...",
    "to": "5511999999999",
    "status": "FAILED",
    "failedAt": "2025-02-10T14:29:30.000Z",
    "errorMessage": "rcs_not_supported"
  }
}

rcs.cancelled

{
  "event": "rcs.cancelled",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T12:00:00.000Z",
  "data": {
    "rcsId": "clxx456...",
    "to": "5511999999999",
    "status": "CANCELLED"
  }
}

Próximos pasos

Quick Start: primer envío
Introducción: ciclo de estados
Instancias RCS: agentes de marca
Ámbitos: permisos de la clave
Webhooks (guía general)

API RCS

Mensagens

Instâncias

Inbound

Eventos de Webhooks

En pocas palabras

Cómo llega el POST

Qué debe responder su servidor

Referencia por evento

Payload de cada evento

Próximos pasos

​En pocas palabras

​Cómo llega el POST

​Qué debe responder su servidor

​Referencia por evento

​Payload de cada evento

​Próximos pasos

En pocas palabras

Cómo llega el POST

Qué debe responder su servidor

Referencia por evento

Payload de cada evento

Próximos pasos