The Zenvia Conversion API allows external systems to be notified about specific events on the platform using Webhooks.

A Webhook is an HTTP POST request sent to a previously registered URL, containing information about the event that occurred.

Available Events (Topics)

The events that can be notified include:

• Prospect creation: Notification sent after receiving and validating a lead.
• Quote update: Notification of status changes.
• Interaction resolution: When a consultant closes an interaction.

How to Register Notifications

To set up notifications, follow these steps:

1. Obtain an API Key: Required to access the API.
2. Register a subscription: Specify the events (Topics) you want to track and provide the URL for notifications (callbackURL) in the API's Notifications section.
3. Receive notifications: Whenever the event occurs, the API will send an HTTP POST request to the registered URL.

Practical Examples

Registering a Subscription

To register a subscription for the prospect creation event, send the following request:

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"  
}

Webhook Example Received

When a prospect is created, your system will receive an HTTP POST request with the following body:

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

Querying Registered Subscriptions

To list all existing subscriptions, send the following request:

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

The response will be similar to:

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

Requirements

Make sure you have an active API Key to use the API features.