La API de Zenvia Conversion permite notificar sistemas externos sobre eventos específicos en la plataforma, utilizando Webhooks.

Un Webhook es una solicitud HTTP POST enviada a una URL previamente registrada, que contiene información sobre el evento ocurrido.

Eventos disponibles (Topics)

Los eventos que pueden ser notificados incluyen:

• Creación de prospecto: Notificación después de recibir y validar un lead.
• Actualización de cotización: Notificación de cambios de estado.
• Resolución de interacción: Cuando un consultor finaliza una interacción.

Cómo registrar notificaciones

Para configurar notificaciones, siga los pasos a continuación:

1. Obtenga una API Key: Necesaria para acceder a la API.
2. Registre una suscripción (subscription): Especifique los eventos (Topics) que desea seguir e ingrese la URL para las notificaciones (callbackURL) en la sección Notifications de la API.
3. Reciba notificaciones: Siempre que ocurra el evento, la API enviará una solicitud HTTP POST a la URL registrada.

Ejemplos prácticos

Registro de una suscripción

Para registrar una suscripción para el evento de creación de un prospecto, envíe la siguiente solicitud:

POST https://api.zenvia.com/v1/subscriptions  
Content-Type: application/json  
Authorization: Bearer {sua-api-key}  


{  
  "topic": "lead.created",  
  "callbackUrl": "https://seu-sistema.com/webhooks/lead"  
}

Ejemplo de Webhook recibido

Cuando se cree un prospecto, su sistema recibirá una solicitud HTTP POST con el siguiente cuerpo:

{  
  "topic": "lead.created",  
  "eventTime": "2024-12-09T15:30:00Z",  
  "data": {  
    "leadId": "12345",  
    "name": "João Silva",  
    "email": "[email protected]",  
    "phone": "+5511999999999"  
  }  
}

Consulta de suscripciones registradas

Para listar todas las suscripciones existentes, envíe la siguiente solicitud:

GET https://api.zenvia.com/v1/subscriptions  
Authorization: Bearer {sua-api-key}  

La respuesta será similar a:

[  
  {  
    "id": "subscription1",  
    "topic": "lead.created",  
    "callbackUrl": "https://seu-sistema.com/webhooks/lead"  
  },  
  {  
    "id": "subscription2",  
    "topic": "interaction.resolved",  
    "callbackUrl": "https://seu-sistema.com/webhooks/interacao"  
  }  
]

Requisitos

Asegúrese de tener una API Key activa para utilizar los recursos de la API.