Webhooks & REST API
Conviro provides webhooks for real-time event notifications and a REST API for programmatic access to all platform features.
Webhooks
What Are Webhooks?
Webhooks send an HTTP POST request to your server whenever a specific event occurs in Conviro. This allows you to react in real time without polling.
Available Events
| Event | Fires When |
|---|---|
message.new | A new message is sent (by visitor or bot) |
session.started | A new conversation session begins |
session.closed | A conversation is closed |
session.handoff | A conversation is handed off to a human agent |
lead.captured | A new lead is captured |
contact.created | A new contact is created |
ticket.created | A support ticket is opened |
csat.submitted | A CSAT rating is submitted |
Setup
- Navigate to Dashboard -> Settings -> Webhooks.
- Click Add Webhook.
- Enter your endpoint URL (must be HTTPS).
- Select the events you want to receive.
- Click Save.
Security: HMAC-SHA256 Signing
Every webhook payload is signed with HMAC-SHA256 using your webhook secret. Verify the signature on your server to ensure authenticity:
X-Conviro-Signature: sha256=<hex_digest>Compare this header against the HMAC-SHA256 digest of the raw request body using your webhook secret.
Retry Policy
If your endpoint returns a non-2xx status code, Conviro retries up to 3 times with exponential backoff (1 min, 5 min, 30 min).
REST API
Authentication
- Generate an API key at Dashboard -> Settings -> API Keys -> Create Key.
- Include it in the
Authorizationheader:
Authorization: Bearer sk_your_api_key_hereKey Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/chatbots | List all chatbots |
| GET | /api/chatbots/:id | Get chatbot details |
| GET | /api/sessions | List sessions (with filters) |
| GET | /api/sessions/:id/messages | Get messages for a session |
| POST | /api/sessions/:id/messages | Send a message to a session |
| GET | /api/contacts | List contacts |
| POST | /api/contacts | Create a contact |
| GET | /api/leads | List leads |
| POST | /api/leads | Create a lead |
| GET | /api/analytics/overview | Get analytics summary |
Rate Limits
- Free plan: 60 requests/minute
- Starter: 120 requests/minute
- Pro: 300 requests/minute
- Growth+: 600 requests/minute
Rate limit headers are included in every response:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200Full Documentation
Visit /developers for the complete API reference with request/response examples.