Integración
Webhooks
Recibe en tu sistema, en tiempo real, los mensajes entrantes y los cambios de estado de mensajes e instancias, con firma HMAC para verificar que vienen de Chat Digital.
Descripción
Un webhook es una dirección (URL) de tu sistema a la que Chat Digital avisa cuando pasa algo: llega un mensaje, cambia el estado de uno enviado o una instancia se conecta o desconecta. Así tu sistema no tiene que preguntar a cada rato. Solo los administradores de la cuenta pueden configurarlos.
Guía de implementación
- Publica en tu sistema una URL HTTPS que reciba POST con JSON
- Crea el webhook con esa URL y los eventos que necesitas
- Guarda el secreto de firma y verifica la firma en tu sistema
- Haz clic en «Probar» y revisa el historial de entregas
Depende de
Lo usan
Funcionalidades
- Registrar URLs públicas que reciben eventos por POST
- Eventos: message.received, message.status e instance.status
- Limitar un webhook a una instancia
- Secreto de firma (HMAC-SHA256) que se muestra una sola vez; se puede rotar
- Botón «Probar» que envía un evento de prueba
- Historial de entregas con código de respuesta, intentos y reintento manual
- Activar y desactivar sin borrar la configuración
Manual de usuario
Crear un webhook #
Necesitas una URL pública de tu sistema que acepte peticiones POST con JSON.
- Paso 1: Entra a Webhooks y haz clic en «Nuevo webhook»
- Paso 2: Escribe la «URL»Debe ser pública (no se aceptan IPs privadas ni localhost). Se recomienda HTTPS.
- Paso 3: Marca los «Eventos»message.received (llega un mensaje nuevo), message.status (cambia el estado de un mensaje enviado) e instance.status (cambia el estado de una instancia).
- Paso 4: Opcional: elige una «Instancia»«Todas las instancias» recibe eventos de cualquiera.
- Paso 5: Haz clic en «Crear webhook»Aparece la ventana «Webhook creado» con el «Secreto de firma».
- Paso 6: Copia el secreto con «Copiar al portapapeles» y haz clic en «Ya lo guardé»
Verificar la firma #
- Inicio: Llega el POST
- Decisión: ¿Firma válida y reciente?
- Atención: No: responde 401
- Paso: Sí: responde 2xx en < 10 s
- Fin: Procesa el eventoIgnora repetidos
Cada entrega llega con los headers X-WhatsA-Event (tipo de evento), X-WhatsA-Delivery (identificador de la entrega), X-WhatsA-Timestamp (momento del envío) y X-WhatsA-Signature (sha256=<hex>). La firma es HMAC-SHA256 del texto «<timestamp>.<cuerpo crudo>» con tu secreto. Tu sistema debe calcularla con el cuerpo tal como llegó (sin volver a convertir el JSON) y compararla; si no coincide, rechaza la petición. La pantalla Webhooks incluye un ejemplo completo en «Cómo verificar la firma».
Probar el webhook #
Antes de depender del webhook, comprueba que tu sistema lo recibe.
- Paso 1: En la lista de webhooks, haz clic en «Probar»Verás «Evento de prueba encolado. Revisa el historial de entregas.» El botón está deshabilitado si el webhook está inactivo.
- Paso 2: Haz clic en «Entregas» para ver el resultado
Historial de entregas y reintentos #
La pantalla «Historial de entregas» muestra cada envío con su evento, estado (Pendiente, Entregado o Fallido), número de intentos, última respuesta (código HTTP o error) y próximo intento. Si tu sistema no responde 2xx en menos de 10 segundos, Chat Digital reintenta con espera creciente (10 s, 30 s, 2 min, 10 min, 30 min, 1 h y 3 h: hasta 8 intentos).
- Paso 1: Haz clic en «Entregas» en la fila del webhook
- Paso 2: Haz clic en «Ver» para revisar el «Cuerpo enviado» y el último error
- Paso 3: Corrige el problema en tu sistema
- Paso 4: En una entrega «Fallido», haz clic en «Reintentar»Verás «Entrega reencolada.»
Editar, rotar el secreto, desactivar o eliminar #
Administra cada webhook desde los botones de su fila.
- Paso 1: «Editar»: cambia URL, eventos, instancia o la casilla «Activo»; guarda con «Guardar cambios»
- Paso 2: «Desactivar» / «Activar»: pausa o reanuda los envíos sin borrar la configuración
- Paso 3: «Rotar secreto»: genera un secreto nuevoEl actual deja de ser válido de inmediato: actualízalo en tu sistema.
- Paso 4: «Eliminar»: deja de enviar eventos a esa URLNo se puede deshacer.
Preguntas frecuentes
Mis entregas salen como «Fallido». ¿Qué reviso?
Abre «Entregas» y mira «Última respuesta»: un código 4xx/5xx viene de tu sistema; un error de conexión o timeout indica que la URL no es accesible o tardó más de 10 segundos. Corrige y usa «Reintentar».
¿Por qué recibí el mismo evento dos veces?
Si tu sistema no respondió 2xx a tiempo, se reintenta aunque sí lo haya procesado. Guarda el identificador de la entrega (X-WhatsA-Delivery) o el eventId y descarta los repetidos.