Saltar al contenido principal
Un webhook es el timbre de tu servidor: cuando sucede algo en Notifique (mensaje enviado, entregado, respuesta del cliente…), lo hacemos sonar con un JSON POST en tu URL.

​
¿Qué es un webhook?

Es una URL HTTPS en su sistema que recibe alertas automáticas de Notifique. En lugar de sondear la API y preguntar “¿se entregó?”, espera a que llegue la alerta. Piense en ello como una notificación automática, pero para su backend.

​
¿Para qué sirve?

Con los webhooks puedes:
  • Saber de inmediato cuándo se envió, entregó, leyó o falló un mensaje
  • Automatizar pedidos, CRM, facturación y bots sin consultar el panel
  • Procesar los mensajes que te envían los clientes (WhatsApp, Telegram, SMS)
  • Monitorizar conexión de instancia (QR, conectado, desconectado)
  • Seguir clics en enlaces cortos y eventos de formularios

​
¿Cuándo usarlo?

​
Cómo configurar

​
1. Prepare su endpoint

Cree una ruta HTTPS que acepte POST JSON y responda 2xx rápidamente. Ejemplo: https://yoursite.com/webhooks/notifique Si el procesamiento es pesado, haga cola de su lado y devuelva 200 inmediatamente. Como abrir el timbre y atender la visita más tarde.

​
2. Regístrese en el panel

Abra Desarrollador → Webhooks, cree un webhook y seleccione los eventos que le interesen. También puede registrarse a través de la API con ámbitos webhooks:manage y webhooks:read. ¿Necesita una clave? Consulte Claves API. Guarde el secret de la respuesta. Lo usa para validar cada POST.

​
Encabezados HTTP personalizados

Puede enviar hasta 10 encabezados en headers. Los valores se guardan cifrados y se envían en la verificación inicial, las entregas y los reintentos.
Los nombres admiten hasta 128 caracteres y los valores hasta 2.048; no se permiten saltos de línea. Host, Content-Length, Content-Type, Transfer-Encoding, Connection y X-Notifique-* están reservados. Las respuestas GET muestran los nombres con valores enmascarados (por ejemplo, Bearer ********). Use PATCH /v1/webhooks/{id} para cambiar encabezados; envíe {"headers": {}} para eliminarlos todos. En PUT, puede reenviar los valores enmascarados para mantener el secreto actual.

​
Validación de URL al registrar

Al registrar en el panel o vía API, Notifique envía un POST de verificación con cuerpo JSON a la URL antes de aceptar el webhook. Si tu endpoint exige autenticación, responde 401 o 403 en la verificación. La verificación también envía headers personalizados, X-Notifique-Signature y X-Notifique-Timestamp; valida la firma en las entregas reales.

​
3. Validar la firma

Cada POST incluye X-Notifique-Signature y X-Notifique-Timestamp. Calcule HMAC-SHA256 del secreto con {timestamp}.{raw body} y rechace marcas de tiempo fuera de 5 minutos. Detalles en la sección Encabezados y firma a continuación.

​
4. Manejar reintentos

Si su endpoint falla, lo volvemos a intentar a los 5 min, 30 min y 2 h. Responda 2xx rápidamente.

​
Sandbox vs producción

  • Sandbox (sk_test_...): mismos nombres de eventos; la carga útil incluye sandbox: true
  • Producción (sk_live_...): eventos reales a partir de tráfico en vivo
Simule eventos en Desarrollador → Bandeja de entrada Sandbox. Más en Modo Sandbox.

​
Formato de carga útil

Todas las solicitudes son POST con Content-Type: application/json. El cuerpo sigue esta estructura:

​
Encabezados y firma

  • Cálculo HMAC: hash = HMAC-SHA256(secret, timestamp + "." + body) (body = cuerpo POST sin procesar).
  • Anti-replay: Rechace solicitudes con marca de tiempo fuera de una ventana (ej. 5 minutos).

​
Mensajes entrantes

Para procesar lo que el cliente envió (WhatsApp, Telegram, SMS):
  1. Suscríbase al evento en el webhook
  2. Configure entrantes en Configuración → Mensajes recibidos
El webhook le avisa con un resumen. Para descargar medios (audio, imagen, documento) en WhatsApp, use inboundId vía API. Guía completa: Mensajes entrantes y respuestas.

​
Buenas prácticas

  1. HTTPS siempre en la URL registrada
  2. Responda 2xx rápido y procese en segundo plano
  3. Valide la firma en cada POST
  4. Suscríbase solo a eventos que su integración consume
Más detalles: Seguridad y confiabilidad.

​
Eventos por canal

Cada canal tiene sus propios eventos. Seleccione solo lo que necesita:

WhatsApp

Envío, entrega, entrantes, instancia y llamadas

SMS

Envío, DLR, MO y respuestas

Telegram

Envío, entrantes e instancia

Instagram

Envío, comentarios y entrantes

Email

Envío, apertura, clic y rebote

Push

Envío, entrega y clic

RCS

Envío, entrega y fallo

Voice

Llamadas y grabaciones

Formularios

Suscripción, confirmación y baja

Enlaces cortos

Clics y conversiones

Números de teléfono

Ciclo de vida del número contratado

Automatizaciones

Ciclo de vida activar, pausar y ejecutar

Plantillas (Meta)

Aprobación, rechazo y categoría
Evento de reputación del espacio de trabajo (trust.score_changed): consulte Trust Factor.

​
Próximos pasos