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: 

1. Haz clic en la opción Crear Nuevo en Tokens;
2. Ingresa un Nombre para identificación del Token;
3. 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. 
4. Finaliza haciendo clic en Guardar.

Listo. Se mostrará una nueva pantalla con tu clave. Guarda este código de forma segura, ya que este será el único momento en que estará disponible. 

💡 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 permiten que recibas eventos en la URL configurada para recibir la información deseada.

Sigue las instrucciones en la pantalla de Tokens y Webhooks:

1. Haz clic en la opción Crear Nuevo en Webhooky selecciona las siguientes opciones:
   • URL: Indica la URL válida donde se recibirán las notificaciones automáticas.
     
   • Estado: Elige entre Activo o Inactivo. La diferencia está relacionada con la recepción automática de notificaciones de eventos.
   • Versión: Selecciona el tipo de versión, haciendo referencia a una iteración específica del servicio de webhook para indicar actualizaciones o cambios a lo largo del tiempo.
   • Tipo de evento: Indica el tipo de evento deseado: Mensaje o Estado del mensaje. Los eventos de mensaje notifican sobre el contenido, mientras que los eventos de estado se enfocan en la entrega o procesamiento del mensaje.
   • Canal: Elige el canal para recibir notificaciones automáticas solo de eventos relacionados con ese canal.
   • Cabeceras: Completa los campos Llave y Valor para configurar los encabezados HTTP, como por ejemplo "Content-Type: application/json". Personaliza según los requisitos de autenticación del destino.

2. Si lo prefieres, puedes guardar el Webhook inmediatamente después de completar la información básica, sin configurar la autenticación OAuth2. La configuración de OAuth2 es opcional y se puede realizar más adelante para añadir mayor seguridad en la recepción de eventos.

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.

1. Al crear o editar un Webhook, habilita la opción Autenticación OAuth.
2. 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).

3. 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.