Webhooks et API REST

Conviro propose des webhooks pour recevoir des notifications d’événements en temps réel, ainsi qu’une API REST pour accéder par programmation à toutes les fonctionnalités de la plateforme.

Webhooks

Qu’est-ce qu’un webhook ?

Les webhooks envoient une requête HTTP POST à votre serveur dès qu’un événement précis se produit dans Conviro. Vous pouvez ainsi réagir en temps réel, sans interrogation périodique (polling).

Événements disponibles

Événement	Déclenché lorsque
`message.new`	Un nouveau message est envoyé (par le visiteur ou le bot)
`session.started`	Une nouvelle session de conversation commence
`session.closed`	Une conversation est fermée
`session.escalated`	Une conversation est escaladée
`lead.captured`	Un nouveau lead est capturé
`lead.created`	Une fiche de lead est créée
`lead_form.submitted`	Un formulaire de lead est soumis
`handoff.requested`	Un transfert vers un agent humain est demandé
`csat.submitted`	Une note CSAT est envoyée
`csat.received`	Un résultat CSAT est enregistré
`ai.failed`	L'IA ne parvient pas à produire une réponse
`ticket.created`	Un ticket de support est ouvert
`ticket.resolved`	Un ticket de support est résolu
`contact.created`	Un nouveau contact est créé
`contact.updated`	Un contact est mis à jour
`contact.merged`	Deux contacts sont fusionnés
`contact.deleted`	Un contact est supprimé

Le formulaire de webhook propose aussi Tous les événements, qui abonne à chacun des événements ci-dessus (stocké sous forme de joker *) ; un même webhook accepte également une liste de noms d'événements séparés par des virgules.

Configuration

Rendez-vous dans Dashboard -> Développeurs -> Webhooks.
Cliquez sur Add Webhook.
Saisissez l’URL de votre endpoint (elle doit être en HTTPS).
Sélectionnez les événements que vous souhaitez recevoir.
Cliquez sur Save.

Sécurité : signature HMAC-SHA256

Chaque payload de webhook est signé en HMAC-SHA256 à l’aide de votre secret de webhook. Vérifiez la signature sur votre serveur pour garantir l’authenticité :

X-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt>          # only on a retried delivery

Le digest est calculé sur <unix_timestamp>.<corps_brut_de_la_requête> : vérifier le corps seul ne correspondra jamais. Découpez l'en-tête sur ,, lisez les valeurs t= et v1=, recalculez le HMAC-SHA256 de t + '.' + rawBody avec votre webhook secret, puis comparez les deux digests en temps constant. Rejetez une livraison dont l'horodatage a plus de quelques minutes, afin qu'une charge utile interceptée ne puisse pas être rejouée. Remarque : Envoyer un test vers une URL qui n'est pas un webhook enregistré est livré sans signature — il n'y a aucun secret pour le signer ; testez votre vérification sur un endpoint enregistré.

Politique de nouvelle tentative

Si votre endpoint renvoie un code de statut différent de 2xx, Conviro effectue jusqu’à 3 nouvelles tentatives avec un backoff exponentiel (1 min, 5 min, 30 min).

API REST

Authentification

Générez une clé d’API dans Dashboard -> Développeurs -> Clés API -> Créer une clé API.
Incluez-la dans l’en-tête Authorization :

Authorization: Bearer sk_your_api_key_here

> La clé n'est affichée qu'une seule fois. La création exige au moins une portée (scope) — Créer reste désactivé tant que vous n'en choisissez pas une — et la valeur sk_ complète apparaît une seule fois, dans une boîte de dialogue qui, volontairement, ne se ferme ni avec Échap ni en cliquant à l'extérieur. Ensuite, seul le préfixe reste lisible ; le reste est un hachage bcrypt et ne peut pas être récupéré. Copiez-la avant de fermer la boîte de dialogue. Si vous la perdez, créez une nouvelle clé et révoquez l'ancienne.

Principaux endpoints

Méthode	Endpoint	Description
GET	`/api/chatbots`	Lister tous les chatbots
GET	`/api/chatbots/:id`	Obtenir les détails d’un chatbot
GET	`/api/sessions`	Lister les sessions (avec filtres)
GET	`/api/sessions/:id/messages`	Obtenir les messages d’une session
POST	`/api/sessions/:id/messages`	Envoyer un message dans une session
GET	`/api/contacts`	Lister les contacts
POST	`/api/contacts`	Créer un contact
GET	`/api/leads`	Lister les leads
POST	`/api/leads`	Créer un lead
GET	`/api/analytics/overview`	Obtenir le résumé des statistiques

Limites de débit

Forfait Free : 60 requêtes/minute
Starter : 120 requêtes/minute
Pro : 300 requêtes/minute
Growth+ : 600 requêtes/minute

Les en-têtes de limite de débit sont inclus dans chaque réponse :

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Documentation complète

Consultez /developers pour la référence complète de l’API, avec des exemples de requêtes et de réponses.