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.escalated | A conversation is escalated |
lead.captured | A new lead is captured |
lead.created | A lead record is created |
lead_form.submitted | A lead form is submitted |
handoff.requested | A handover to a human agent is requested |
csat.submitted | A CSAT rating is submitted |
csat.received | A CSAT result is recorded |
ai.failed | The AI fails to produce an answer |
ticket.created | A support ticket is opened |
ticket.resolved | A support ticket is resolved |
contact.created | A new contact is created |
contact.updated | A contact is updated |
contact.merged | Two contacts are merged |
contact.deleted | A contact is deleted |
The webhook form also offers All events, which subscribes to every event above (stored as the wildcard *), and a single webhook accepts a comma-separated list of event names.
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-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt> # only on a retried deliveryThe digest is computed over <unix_timestamp>.<raw_request_body>, so verifying the body on its own will never match. Split the header on ,, read the t= and v1= values, recompute the HMAC-SHA256 of t + '.' + rawBody with your webhook secret, and compare the two digests in constant time. Reject a delivery whose timestamp is more than a few minutes old, so a captured payload cannot be replayed. Note: Send test against a URL that is not a saved webhook is delivered unsigned — there is no secret to sign it with; test your verification against a saved endpoint.
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_here> The key is shown once. Creating a key requires at least one scope — Create stays disabled until you pick one — and the full sk_ value is displayed a single time, in a dialog that deliberately does not close on Escape or a backdrop click. Afterwards only the prefix is kept in readable form; the rest is a bcrypt hash and cannot be recovered. Copy it before you close the dialog. If you lose it, create a new key and revoke the old one.
Key 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.