Utilice Tokens & Webhooks para generar credenciales de autenticación y configurar URLs para recibir notificaciones automáticas de eventos, facilitando la integración de Zenvia Customer Cloud con otros sistemas.
Ambos se usan para integrar e interactuar mediante APIs, garantizando una comunicación segura entre sistemas.
💡 Para configurar y utilizar las APIs, recomendamos contar con el apoyo de un desarrollador. La documentación completa está disponible en Zenvia APIs.
Cómo acceder
La pantalla de creación de Tokens y Webhooks permite el uso de las APIs multicanal.
Para acceder, sigue las instrucciones:
En el menú lateral, haz clic en Configuraciones > Tokens y Webhooks.
Crear nuevo token
El Token es una clave de autenticación con nuestras APIs. Es con ella que realizarás las integraciones y demás solicitudes. Para crear uno, sigue estos pasos en la pantalla de Tokens y Webhooks:
- Haz clic en la opción Crear Nuevo en Tokens;
- Ingresa un Nombre para identificación del Token;
- Elige el tipo de autenticación:
- Estándar: Utiliza solo el token para validar la conexión entre sistemas.
- Con firma: Incorpora una firma digital al token, proporcionando una capa adicional de seguridad.
- Finaliza haciendo clic en Guardar.
💡 Consejo: Si lo prefieres, haz clic en el botón Cargar .CSV para guardar el archivo con la clave.
Si deseas eliminar el Token, regresa a la pantalla de Tokens y Webhooks y haz clic en la opción Eliminar.
Crear nuevo Webhook
Los Webhooks son opcionales y le permiten recibir eventos en la URL configurada para obtener la información deseada.
Siga las instrucciones en la pantalla Tokens & Webhooks:
1. Haga clic en la opción Crear nuevo webhook.
2. Rellene la siguiente información:
| Campo | Descripción |
|---|---|
| URL | Ingrese la URL válida a donde se enviarán las notificaciones automáticas. |
| Estado | Elija entre Activo o Inactivo - solo los webhooks activos reciben eventos. |
| Versión | Indica la iteración de la estructura del webhook (utilizada para actualizaciones y compatibilidad). |
| Tipo de evento | Seleccione el tipo de evento que desea recibir (detallado a continuación). |
| Canal | Elija el canal para recibir notificaciones solo de eventos relacionados con él. |
| Encabezados | Agregue pares Clave: Valor, como Content-Type: application/json. Úselo según las exigencias de autenticación del destino. |
3. Si lo prefiere, puede guardar el Webhook inmediatamente después de rellenar la información básica, sin configurar la autenticación OAuth2. La configuración de OAuth2 es opcional y puede hacerse posteriormente para añadir mayor seguridad a la recepción de los eventos.
Tipos de eventos disponibles
Los webhooks pueden configurarse para diferentes tipos de evento, de acuerdo con el contexto deseado.
| Tipo de evento | Descripción |
|---|---|
| Mensaje | Notifica el contenido de los mensajes enviados o recibidos. |
| Estado del mensaje | Envía actualizaciones sobre el estado del mensaje, como envío, entrega o lectura. |
| Conversación | Notifica eventos relacionados con el inicio, actualización o cierre de conversaciones. |
| Mensaje de la conversación | Envía notificaciones sobre mensajes intercambiados dentro de conversaciones específicas. |
| Agente especialista de soporte | Notifica ejecuciones de agentes especialistas de soporte configurados con la acción Webhook. Este tipo de evento se utiliza cuando un agente especialista de soporte es ejecutado y tiene como acción el envío de un webhook a una URL específica. Cómo funciona:
Para entender cómo configurar y utilizar esta acción, consulte los artículos sobre Agentes especialistas de soporte: qué son y cómo crearlos y Acciones de los agentes especialistas de soporte. |
Webhooks con OAuth2
Para garantizar mayor seguridad en el envío de notificaciones, utiliza la autenticación OAuth2. Con ella, Zenvia obtiene automáticamente un token de acceso válido antes de enviar cada webhook, protegiendo tu sistema contra accesos no autorizados.
- Al crear o editar un Webhook, habilita la opción Autenticación OAuth.
- Completa los siguientes campos de autenticación:
- URL de autenticación: Indica la URL donde se hará la solicitud OAuth2 para obtener el token de acceso.
- Cabeceras (headers): Añade pares clave-valor que serán enviados en la solicitud de autenticación, si es necesario (ej: Content-Type: application/json).
- Parámetros de URL (Query Params): Si la autenticación requiere parámetros adicionales en la URL, infórmalos en los campos de clave y valor.
- Tipo de permiso (Grant Type): Campo fijo con el valor Client Credentials, utilizado para autenticación entre sistemas.
- Client ID y Client Secret: Datos proporcionados por el servicio autenticador para validar tu integración.
- Refresh token (opcional): Rellena este campo si la autenticación OAuth2 utiliza token de renovación.
- Tiempo de expiración en segundos (opcional): Define, si es necesario, el tiempo de validez del token. Ingresa un número en segundos (ej: 3600 = 1 hora).
Después de completar los datos de OAuth2, verifica que los campos principales del Webhook ya hayan sido configurados (como canal, tipo de evento, URL de entrega y encabezados HTTP). Si aún no lo hiciste, completa esta información antes de hacer clic en Guardar.
Si deseas eliminar un Webhook, regresa a la pantalla de Tokens y Webhooks y haz clic en la opción Eliminar.
¡Listo! Con el Webhook configurado con OAuth2, ya puedes recibir notificaciones seguras e integrarlas con los canales de Zenvia. Consulta nuestra documentación técnica para más detalles o realiza pruebas en el Sandbox.
Cómo funciona el envío de webhooks
Para garantizar estabilidad y rendimiento, el sistema monitorea automáticamente el tiempo de respuesta de las URLs que reciben webhooks. Si hay problemas constantes, la prioridad de envío se reduce o los envíos pueden ser suspendidos.
Reglas de funcionamiento
- Tiempo de respuesta: la URL debe responder en un máximo de 5 segundos.
- Timeout (sin respuesta en 5 segundos) equivale a 10 errores comunes.
- 1 timeout ya coloca el webhook en estado degradado, con prioridad reducida.
- 50 timeouts consecutivos vuelven el webhook inactivo, y se suspenden los envíos.
Buena práctica
Responda al webhook lo más rápido posible, incluso si el procesamiento del mensaje se realiza después. Esto ayuda a mantener su webhook con alta prioridad y evita retrasos o interrupciones.