Webhooks en REST API
Conviro biedt webhooks voor realtime meldingen van events en een REST API voor programmatische toegang tot alle functies van het platform.
Webhooks
Wat zijn webhooks?
Webhooks sturen een HTTP POST-verzoek naar je server zodra er een bepaald event plaatsvindt in Conviro. Zo reageer je in realtime, zonder te pollen.
Beschikbare events
| Event | Wordt geactiveerd wanneer |
|---|---|
message.new | Er een nieuw bericht wordt verstuurd (door bezoeker of bot) |
session.started | Er een nieuwe gesprekssessie begint |
session.closed | Een gesprek wordt gesloten |
session.escalated | Een gesprek wordt geëscaleerd |
lead.captured | Er een nieuwe lead wordt vastgelegd |
lead.created | Er een leadrecord wordt aangemaakt |
lead_form.submitted | Er een leadformulier wordt ingediend |
handoff.requested | Er een overdracht naar een menselijke agent wordt aangevraagd |
csat.submitted | Er een CSAT-beoordeling wordt gegeven |
csat.received | Er een CSAT-resultaat wordt vastgelegd |
ai.failed | De AI geen antwoord kan produceren |
ticket.created | Er een supportticket wordt geopend |
ticket.resolved | Er een supportticket wordt opgelost |
contact.created | Er een nieuw contact wordt aangemaakt |
contact.updated | Een contact wordt bijgewerkt |
contact.merged | Twee contacten worden samengevoegd |
contact.deleted | Een contact wordt verwijderd |
Het webhookformulier biedt ook Alle events, waarmee je je abonneert op elk event hierboven (opgeslagen als wildcard *); één webhook accepteert daarnaast een door komma's gescheiden lijst met eventnamen.
Instellen
- Ga naar Dashboard -> Developers -> Webhooks.
- Klik op Add Webhook.
- Voer de URL van je endpoint in (moet HTTPS zijn).
- Selecteer de events die je wilt ontvangen.
- Klik op Save.
Beveiliging: ondertekening met HMAC-SHA256
Elke webhook-payload wordt ondertekend met HMAC-SHA256 op basis van je webhook secret. Controleer de handtekening op je server om de echtheid vast te stellen:
X-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt> # only on a retried deliveryDe digest wordt berekend over <unix_timestamp>.<ruwe_request_body>; wie alleen de body controleert, krijgt nooit een match. Splits de header op ,, lees de waarden t= en v1=, herbereken de HMAC-SHA256 van t + '.' + rawBody met je webhook secret en vergelijk beide digests in constante tijd. Weiger een levering waarvan de timestamp ouder is dan enkele minuten, zodat een onderschepte payload niet opnieuw kan worden afgespeeld. Let op: Test verzenden naar een URL die geen opgeslagen webhook is, wordt ongetekend afgeleverd — er is geen secret om mee te ondertekenen; test je verificatie tegen een opgeslagen endpoint.
Herhaalbeleid
Als je endpoint een statuscode buiten de 2xx-reeks teruggeeft, probeert Conviro het maximaal 3 keer opnieuw met exponentiële backoff (1 min, 5 min, 30 min).
REST API
Authenticatie
- Genereer een API-sleutel via Dashboard -> Developers -> API-sleutels -> API-sleutel maken.
- Voeg deze toe aan de
Authorization-header:
Authorization: Bearer sk_your_api_key_here> De sleutel wordt één keer getoond. Een sleutel aanmaken vereist minstens één scope — Aanmaken blijft uitgeschakeld tot je er een kiest — en de volledige sk_-waarde verschijnt precies één keer, in een dialoog die bewust niet sluit met Escape of een klik op de achtergrond. Daarna blijft alleen het voorvoegsel leesbaar; de rest is een bcrypt-hash en is niet te herstellen. Kopieer hem voordat je de dialoog sluit. Ben je hem kwijt, maak dan een nieuwe sleutel aan en trek de oude in.
Belangrijkste endpoints
| Methode | Endpoint | Omschrijving |
|---|---|---|
| GET | /api/chatbots | Alle chatbots weergeven |
| GET | /api/chatbots/:id | Details van een chatbot opvragen |
| GET | /api/sessions | Sessies weergeven (met filters) |
| GET | /api/sessions/:id/messages | Berichten van een sessie opvragen |
| POST | /api/sessions/:id/messages | Een bericht naar een sessie sturen |
| GET | /api/contacts | Contacten weergeven |
| POST | /api/contacts | Een contact aanmaken |
| GET | /api/leads | Leads weergeven |
| POST | /api/leads | Een lead aanmaken |
| GET | /api/analytics/overview | Samenvatting van de analytics opvragen |
Rate limits
- Free-abonnement: 60 verzoeken/minuut
- Starter: 120 verzoeken/minuut
- Pro: 300 verzoeken/minuut
- Growth+: 600 verzoeken/minuut
De rate limit-headers zitten in elke response:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200Volledige documentatie
Ga naar /developers voor de volledige API-referentie met voorbeelden van requests en responses.