Webhooks
Actualizado el
Dónde: Configuración > Integraciones > Webhooks
Para qué sirve:
"Reenvía los eventos entrantes a tu propio servidor". SyBox envía una copia en tiempo real de cada evento seleccionado a una dirección de tu servidor. Los eventos de WhatsApp llegan en el propio formato de Meta. Los mensajes de los clientes en Messenger, Instagram, Telegram, TikTok y Chat en vivo, así como los eventos de conversación (hecha, etiquetas, contactos, tratos, casos CRM), llegan en el propio formato de SyBox. No se envían los mensajes de email ni de SMS.
Quién puede acceder: el administrador principal y los miembros del equipo que tengan el permiso "Administrar canales". Para crear un webhook o reactivar uno en pausa, también necesitas el permiso "Mostrar el número del contacto", ya que las copias contienen los números reales de los clientes.
Eventos disponibles para elegir:
- "Mensaje entrante": un cliente ha enviado un mensaje.
- "Estado del mensaje": un mensaje enviado por ti ha cambiado a enviado, entregado, leído o fallido.
- "Reacción": un cliente ha reaccionado a un mensaje.
- "Conversación marcada como hecha": una conversación se marcó como hecha, ya sea por un miembro del equipo, por una automatización o por sí sola tras el silencio del cliente.
- "Etiqueta añadida o quitada": se añadió una etiqueta a una conversación o se quitó de ella.
- "Contacto creado o actualizado": se creó un contacto nuevo o cambiaron el nombre, el correo electrónico o los campos de un contacto. La importación de contactos no envía estos eventos.
- "Trato cerrado": se registró un trato en una conversación.
- "Caso CRM abierto o cerrado": se abrió un caso CRM, o se cerró como resuelto, no resuelto o cancelado. Un caso no pertenece a ningún número, por lo que solo lo recibe un webhook que cubra todos los números, no uno limitado a algunos números.
Los cinco últimos llegan en el propio formato de SyBox para todos los canales. La página de Documentación para desarrolladores muestra un ejemplo de cada uno.
- "Transcripción de voz" (opción adicional): la nota de voz se retiene brevemente (hasta unos dos minutos) para que se envíe acompañada de su texto transcrito. Viene desactivada por defecto.
- Ve a Configuración > Integraciones > Webhooks.
- Haz clic en "Añadir webhook".
- Introduce un "Nombre".
- Introduce la "URL de destino". Debe ser "Una dirección https pública a la que podamos llegar". Las direcciones http estándar y las redes privadas o internas serán rechazadas.
- En "Eventos", activa al menos un evento. "Mensaje entrante" está seleccionado por defecto.
- Opcional: activa "Transcripción de voz" para recibir las notas de voz acompañadas de su transcripción en texto.
- En "Números", mantén activada la opción "Todos los números" para abarcar cualquier línea de WhatsApp. O desactívala y marca solo los números que prefieras.
- Haz clic en Guardar.
- Aparecerá una ventana con la "Clave de firma". "Cópiala ahora — solo se muestra una vez". Guárdala en tu servidor.
Información sobre los envíos:
- Cada entrega utiliza el mismo formato que los webhooks oficiales de WhatsApp de Meta.
- Cada entrega va firmada con tu clave de firma del mismo modo que Meta firma sus webhooks. Si tu servidor ya valida los webhooks de Meta, puede verificar los de SyBox utilizando tu clave de SyBox.
- Si tu servidor no responde con un estado satisfactorio, SyBox reintentará el envío en varias ocasiones, espaciando los intentos de forma progresiva a lo largo de una hora aproximadamente. Pasado ese tiempo, descartará el evento.
- Un mismo evento puede recibirse por duplicado en ocasiones puntuales (por ejemplo, tras un tiempo de espera agotado). Tu servidor debe estar preparado para gestionar duplicados.
- Asegúrate de que el webhook esté activado. Si está desactivado, verás "Activa primero este webhook."
- En su tarjeta, haz clic en "Enviar evento de prueba". Verás "El evento de prueba está en camino. Su resultado aparecerá en Entregas."
- Unos segundos después se abre la lista "Entregas" y muestra la respuesta de tu servidor. La tarjeta también mostrará la última respuesta devuelta por tu servidor junto con su hora. Una respuesta correcta (como "HTTP 200") se mostrará en verde. Un fallo aparecerá en rojo. La indicación "Última entrega: nunca" significa que todavía no se ha procesado ningún envío.
Un evento de prueba tiene "event": "test" y no lleva datos de clientes. Puedes enviar uno cada pocos segundos; si lo intentas antes, verás "Se envió una prueba hace un momento. Inténtalo de nuevo en unos segundos."
- En la tarjeta del webhook, haz clic en "Entregas".
- La lista muestra "Las últimas 50 entregas de los últimos 7 días.", de la más reciente a la más antigua. Cada una muestra su evento, cuándo se intentó y su estado:
- "Entregado": tu servidor respondió con éxito.
- "Pendiente de envío": aún no se ha intentado.
- "Falló, reintentando": tu servidor no respondió con éxito y SyBox lo intentará de nuevo más tarde.
- "No entregado": SyBox dejó de intentarlo.
- También muestra el código HTTP con el que respondió tu servidor, cuánto tardó la respuesta en milisegundos e "Intentos: [número]" cuando se intentó más de una vez. El mensaje en sí no se muestra.
- Para volver a enviar una entrega, haz clic en "Enviar de nuevo" en una entrega cuyo estado sea "Entregado" o "No entregado". Verás "En cola para enviarse de nuevo." Enviar de nuevo requiere el permiso "Mostrar el número del contacto", porque vuelve a enviar los datos del cliente.
Desactivado por sí solo:
Si tu servidor sigue fallando —20 intentos seguidos durante más de una hora—, SyBox desactiva el webhook. La tarjeta muestra en rojo "Desactivado por sí solo tras [número] entregas fallidas seguidas", y el administrador principal recibe una notificación: "Se desactivó un webhook". Sus eventos pendientes se conservan durante 24 horas. Corrige la dirección o tu servidor y vuelve a activar el webhook: los eventos pendientes se enviarán y el contador volverá a empezar desde cero.
- Haz clic en Editar para modificar el nombre, la dirección, los eventos o los números asignados.
- Para sustituir la clave de firma, escribe una nueva en "Clave de firma". Déjala en blanco si deseas mantener la actual ("Déjalo vacío para conservar la clave actual").
- Haz clic en Habilitar / Deshabilitar para pausarlo. Los eventos recibidos mientras esté pausado quedarán en espera. Si lo reactivas pronto, se enviarán.
- Haz clic en Eliminar y confirma en "¿Eliminar este webhook?".
Reglas y mensajes:
- El nombre y la URL de destino son obligatorios, y debe haber al menos un evento activo. De lo contrario, aparecerá el mensaje "Datos incompletos".
- Toda dirección que no sea https pública se rechazará con el mensaje "Una dirección https pública a la que podamos llegar".
He perdido la clave de firma.
No se puede volver a mostrar. Edita el webhook, escribe una clave nueva elegida por ti en "Clave de firma", guárdala y actualiza esa misma clave en tu servidor.
Mi webhook se desactivó y yo no lo hice.
SyBox lo desactivó después de que tu servidor fallara 20 veces seguidas durante más de una hora. Consulta "Desactivado por sí solo" más arriba: repara tu servidor y vuelve a activar el webhook antes de 24 horas para que se envíen los eventos pendientes.
Mi webhook nunca recibe datos.
Primero haz clic en "Enviar evento de prueba" en su tarjeta y mira en "Entregas". Luego comprueba estos cuatro aspectos: (1) El webhook está activado. (2) Hay al menos un evento seleccionado. (3) Incluye el número de WhatsApp correcto o la opción "Todos los números". (4) El canal por el que llegó el mensaje es uno de los que admiten los webhooks (WhatsApp, Messenger, Instagram, Telegram, TikTok o Chat en vivo; no email ni SMS). Por último, comprueba el resultado de la última entrega en la tarjeta.
La tarjeta muestra un error en rojo como HTTP 404 o 500.
SyBox ha podido contactar con tu dirección, pero tu servidor ha devuelto un error. Comprueba la URL y los registros de actividad de tu servidor.
No puedo crear un webhook. Me aparece un aviso de falta de permisos.
Para crear un webhook o reactivar uno en pausa, se requieren los permisos "Administrar canales" y "Mostrar el número del contacto". Contacta con tu administrador.