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 démarre
`session.closed`	Une conversation est fermée
`session.handoff`	Une conversation est transférée à un agent humain
`lead.captured`	Un nouveau lead est capturé
`contact.created`	Un nouveau contact est créé
`ticket.created`	Un ticket de support est ouvert
`csat.submitted`	Une note CSAT est envoyée

Configuration

Rendez-vous dans Dashboard -> Settings -> 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-Conviro-Signature: sha256=<hex_digest>

Comparez cet en-tête au condensé HMAC-SHA256 du corps brut de la requête, calculé avec votre secret de webhook.

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 -> Settings -> API Keys -> Create Key.
Incluez-la dans l’en-tête Authorization :

Authorization: Bearer sk_your_api_key_here

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.