Webhooks

Los webhooks te permiten enviar eventos en tiempo real a cualquier endpoint externo. Úsalos para sincronizar mensajes con tu CRM, activar automatizaciones en n8n/Make/Zapier o crear backends personalizados.

Crear una Suscripción de Webhook

Abre tu Ubicación

Ve a Panel → Ubicaciones y selecciona la ubicación a la que quieres suscribirte.

Abre Configuración

Haz clic en la pestaña Configuración de esa ubicación.

Crear suscripción

Desplázate hasta la sección Webhooks y haz clic en Crear suscripción.

Completa el formulario

Completa el cuadro de diálogo Crear suscripción (consulta los campos a continuación).

Guardar

Haz clic en Crear suscripción para guardar. Si “Enviar un ping de prueba” está habilitado, se enviará un evento ficticio mediante POST a tu endpoint para verificar que funciona.

Campos de la Suscripción

Nombre (obligatorio)

Una etiqueta legible para que puedas identificar la suscripción más tarde (por ejemplo, Sincronización CRM, Manejador Entrante n8n).

URL de Destino

El endpoint HTTPS que recibirá las cargas útiles (payloads) de los eventos.

https://example.com/webhooks

Tu endpoint debe responder con un código de estado 2xx. Las respuestas que no sean 2xx se tratan como fallos.

Seleccionar eventos

Elige exactamente qué eventos deben activar un webhook. Puedes combinar canales en una sola suscripción.

Entrante - se recibe un mensaje de WhatsApp
Saliente - se envía un mensaje de WhatsApp

iMessage

Entrante - se recibe un iMessage
Saliente - se envía un iMessage

SMS

Entrante - se recibe un SMS
Saliente - se envía un SMS

Sistema

Mensaje fallido - un mensaje no pudo entregarse (úsalo para lógica de reintentos o alertas)

Enviar un ping de prueba al crear

Cuando está habilitado, el sistema enviará mediante POST un evento ficticio a tu URL de Destino inmediatamente después de crear la suscripción. Úsalo para confirmar que tu endpoint es accesible y que tu manejador analiza las cargas útiles correctamente.

Déjalo activado para la primera suscripción que crees contra un nuevo endpoint.

El cuerpo del ping de prueba es { "type": "test.ping" }. No está envuelto en el sobre (envelope) descrito abajo.

Formato de Entrega

Todo evento, excepto el ping de prueba, se envía mediante POST como JSON, envuelto en este sobre (envelope):

{
  "version": "1.0",
  "event": "whatsapp.inbound",
  "eventId": "3f9e2b8c-1a2d-4e3f-9b1a-2c3d4e5f6a7b",
  "timestamp": "2026-08-03T14:22:05.123Z",
  "locationId": "loc_2f9a41",
  "payload": { }
}

Campo	Tipo	Descripción
`version`	`string`	Siempre `"1.0"`.
`event`	`string`	El nombre del evento, coincide con lo que seleccionaste al crear la suscripción.
`eventId`	`string`	ID único para esta entrega. Úsalo para deduplicar eventos reintentados.
`timestamp`	`string` (ISO 8601)	Cuándo se despachó el evento.
`locationId`	`string`	La ubicación a la que pertenece el evento.
`payload`	`object`	Datos específicos del evento. Ver Cargas Útiles de Eventos abajo.

Encabezados

Content-Type: application/json
X-WA-Event-Id: <eventId>
X-WA-Timestamp: <unix timestamp, ms>

X-WA-Event-Id coincide con el eventId en el cuerpo.

Cargas Útiles de Eventos

El objeto payload difiere según el canal y el tipo de evento. message.media[].type siempre es uno de image, video, audio, document, file, o unknown.

Mensajes entrantes

whatsapp.inbound, imessage.inbound, sms.inbound - se dispara cuando un contacto envía un mensaje a uno de tus números conectados.

WhatsApp
iMessage
SMS

{
  "messageId": "wamid.HBgLMTU1NTk4NzY1NDMV...",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000", "name": "Recepción" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": {
    "text": "Hola, ¿mi pedido está listo?",
    "media": [{ "url": "https://cdn.example.com/img.jpg", "type": "image" }]
  },
  "transcribedAudio": "Texto transcrito de una nota de voz, cuando está presente"
}

{
  "messageId": "msg_9d41ab",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": { "text": "Voy en camino, llego en 5 min" },
  "meta": { "transcribedAudio": "Texto transcrito de una nota de voz, cuando está presente" }
}

{
  "messageId": "msg_4e17cd",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": { "text": "¿Puedo reprogramar para el viernes?" }
}

Campo	Tipo	Notas
`messageId`	`string`	ID del mensaje del proveedor.
`locationId`	`string`	La ubicación a la que pertenece el evento.
`device.number`	`string`	El número conectado que recibió el mensaje.
`device.name`	`string`	Opcional.
`contact.id`	`string`	ID de contacto en GHL, si el remitente ya es un contacto conocido.
`contact.name`	`string`	Opcional.
`contact.number`	`string`	Número del remitente. Opcional en WhatsApp, donde un remitente puede identificarse solo por `lid`.
`contact.lid` / `contact.waUsername`	`string`	Solo WhatsApp. Campos de identidad opcionales, presentes cuando WhatsApp los envía.
`message.text`	`string`	Opcional. Ausente en mensajes solo con medios.
`message.media`	`array`	Cada elemento tiene `url` y `type`. Puede estar ausente, o ser un arreglo vacío, cuando no hay medios.
`transcribedAudio`	`string`	Transcripción de una nota de voz, cuando la transcripción está habilitada.
`ctwa`	`object`	Solo WhatsApp. Metadatos de anuncio de clic a WhatsApp, presente solo cuando la conversación inició desde un anuncio de WhatsApp.

transcribedAudio está en el nivel superior en WhatsApp, pero anidado bajo meta.transcribedAudio en iMessage y SMS.

Mensajes salientes

whatsapp.outbound, imessage.outbound, sms.outbound - se dispara cuando se envía un mensaje desde un número conectado, ya sea escrito en el dispositivo o enviado por el CRM.

{
  "messageId": "wamid.HBgLMTU1NTk4NzY1NDMV...",
  "source": "crm",
  "contact": { "id": "contact_7be31c", "number": "15559876543" },
  "message": { "text": "¡Tu pedido está listo para recoger!" },
  "device": { "number": "15551230000", "name": "Recepción", "instanceIndex": 0 },
  "locationId": "loc_2f9a41",
  "timestamp": "2026-08-03T14:25:10.500Z"
}

Campo	Tipo	Notas
`messageId`	`string`
`locationId`	`string`	La ubicación a la que pertenece el evento.
`source`	`string`	Cómo se envió el mensaje: `crm` (desde el CRM o una automatización), `device` (escrito en el teléfono/app conectado), `n8n`, o `api`.
`contact.id`	`string`
`contact.number`	`string`
`contact.name`	`string`	Opcional. Suele estar ausente en envíos iniciados por el CRM.
`contact.lid` / `contact.waUsername`	`string`	Solo WhatsApp. Campos de identidad opcionales, igual que en entrantes.
`message.text` / `message.media`		Misma estructura que en entrantes.
`device.number`	`string`	El número conectado que lo envió.
`device.name`	`string`	Opcional.
`device.instanceIndex`	`number`	Opcional. La instancia conectada que lo envió.
`timestamp`	`string` (ISO 8601)

Mensaje fallido

message.failed - se dispara cuando un mensaje saliente en cualquier canal no pudo entregarse tras varios reintentos.

{
  "messageId": "msg_7c6b5a",
  "contactId": "contact_7be31c",
  "message": "Hola, dando seguimiento a tu cita",
  "channelType": "whatsapp",
  "error": {
    "code": "109",
    "type": "WhatsAppFailure",
    "message": "Could not send the message. Please contact Custom Provider Support team"
  },
  "device": { "instanceIndex": 2, "phoneNumber": "15551230000" },
  "receiver": { "phoneNumber": "15559876543", "contactId": "contact_7be31c" },
  "locationId": "loc_2f9a41",
  "timestamp": "2026-08-03T14:30:00.000Z"
}

Campo	Tipo	Notas
`messageId`	`string`
`contactId`	`string`	Opcional.
`message`	`string`	Vista previa opcional del cuerpo del mensaje que falló al enviarse.
`channelType`	`"whatsapp"` \| `"imessage"` \| `"sms"`	Opcional.
`error.code` / `.type` / `.message`	`string`	Detalles del fallo.
`device.instanceIndex`	`number` \| `null`
`device.phoneNumber`	`string` \| `null`	El número conectado que intentó el envío.
`receiver.phoneNumber`	`string`	Número del destinatario.
`receiver.contactId`	`string`	Opcional.
`locationId`	`string`	La ubicación a la que pertenece el evento.
`timestamp`	`string` (ISO 8601)	Cuándo se registró el fallo.

error.code indica por qué falló el envío. Consulta Códigos de Error para ver la lista completa y qué hacer en cada caso.

Se pueden añadir códigos nuevos con el tiempo, así que trata los códigos no reconocidos como un fallo genérico en lugar de asumir una lista fija.

Mejores Prácticas

Usa una suscripción por integración. Mantiene los registros y la rotación simples.
Verifica con el ping de prueba antes de confiar en una suscripción en producción.
Devuelve 2xx rápidamente - delega el trabajo lento a una cola en segundo plano en tu manejador.
Sé idempotente. Los webhooks pueden reentregarse ocasionalmente.
Limita por canal. No te suscribas a eventos que no vas a procesar.

Gestionar Suscripciones

Desde la sección Webhooks en la Configuración de Ubicación puedes:

Ver todas las suscripciones activas y su fecha de creación
Eliminar una suscripción que ya no necesites
Crear suscripciones adicionales para endpoints distintos

Solución de Problemas

El ping de prueba nunca llegó

Confirma que tu endpoint es accesible públicamente (sin localhost / IPs privadas)
Verifica que acepte POST y devuelva 2xx
Comprueba que las reglas de firewall/WAF no estén bloqueando la IP

Los eventos dejaron de dispararse

Asegúrate de que la suscripción no haya sido eliminada
Confirma que la ubicación todavía tiene una instancia conectada para el canal
Revisa los registros de tu endpoint en busca de respuestas 5xx (las entregas fallidas se reintentan unas cuantas veces y luego se descartan)

Eventos duplicados

Los webhooks son al-menos-una-vez. Usa el eventId de nivel superior (también enviado como el encabezado X-WA-Event-Id) para deduplicar de tu lado.

Inicio

Primeros Pasos

WhatsApp

iMessage

SMS

Múltiples Instancias

Seguridad y Calentamiento

Características

Funciones de JS Personalizado

Automatización

Integración externa

Datos y Privacidad

Crear una Suscripción de Webhook

Campos de la Suscripción

Nombre (obligatorio)

URL de Destino

Seleccionar eventos

WhatsApp

iMessage

SMS

Sistema

Enviar un ping de prueba al crear

Formato de Entrega

Encabezados

Cargas Útiles de Eventos

Mensajes entrantes

Mensajes salientes

Mensaje fallido

Mejores Prácticas

Gestionar Suscripciones

Solución de Problemas

​Crear una Suscripción de Webhook

​Campos de la Suscripción

​Nombre (obligatorio)

​URL de Destino

​Seleccionar eventos

​WhatsApp

​iMessage

​SMS

​Sistema

​Enviar un ping de prueba al crear

​Formato de Entrega

​Encabezados

​Cargas Útiles de Eventos

​Mensajes entrantes

​Mensajes salientes

​Mensaje fallido

​Mejores Prácticas

​Gestionar Suscripciones

​Solución de Problemas

Crear una Suscripción de Webhook

Campos de la Suscripción

Nombre (obligatorio)

URL de Destino

Seleccionar eventos

WhatsApp

iMessage

SMS

Sistema

Enviar un ping de prueba al crear

Formato de Entrega

Encabezados

Cargas Útiles de Eventos

Mensajes entrantes

Mensajes salientes

Mensaje fallido

Mejores Prácticas

Gestionar Suscripciones

Solución de Problemas