Webhooks et Integrations

8.1 Qu'est-ce que les Webhooks

Les webhooks permettent a Voki d'envoyer des notifications automatiques a vos systemes externes lorsque des evenements specifiques se produisent. Par exemple, vous pouvez etre notifie lorsqu'un appel est termine pour enregistrer le service dans votre CRM.

Disponibilite : Plans Avance, Professionnel et Enterprise.

8.2 Configurer un Webhook

1. Accedez a « Parametres » > « Webhooks » dans le Panneau de Gestion
2. Cliquez sur « Nouveau Webhook »
3. Remplissez :
   • URL : le endpoint de votre systeme qui recevra les notifications (doit accepter les POST)
   • Evenements : selectionnez les evenements que vous souhaitez recevoir
   • Secret : cle secrete pour la validation HMAC (generee automatiquement ou definie par vous)
4. Cliquez sur « Enregistrer »

8.3 Evenements Disponibles

Evenement	Description	Declenchement
call.created	Appel cree	Le client entre dans la file
call.assigned	Appel attribue	L'agent accepte l'appel
call.started	Appel demarre	Connexion WebRTC etablie
call.completed	Appel termine	Appel termine normalement
call.missed	Appel manque	Le client a quitte la file sans etre servi
customer.created	Client cree	Nouveau client enregistre

8.4 Signature HMAC-SHA256

Chaque notification envoyee par Voki inclut une signature HMAC-SHA256 dans l'en-tete X-Voki-Signature. Utilisez cette signature pour valider que la requete provient bien de Voki :

# Exemple de validation en Python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

// Exemple de validation en Node.js
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

8.5 Format du Payload

Chaque notification est envoyee sous forme de requete HTTP POST avec le format suivant :

{
  "event": "call.completed",
  "timestamp": "2026-02-20T14:30:00Z",
  "data": {
    "id": "uuid-de-lappel",
    "status": "completed",
    "duration_seconds": 342,
    "department_id": "uuid-du-departement",
    "attendant_id": "uuid-de-lagent",
    "customer": {
      "name": "Nom du Client",
      "email": "client@email.com"
    }
  }
}

En-tetes envoyes :

Content-Type: application/json
X-Voki-Signature: sha256=abc123...
X-Voki-Event: call.completed
X-Voki-Delivery: uuid-de-la-livraison

8.6 Livraisons et Renvoi

Chaque tentative de livraison de webhook est enregistree. Sur la page de details du webhook, vous pouvez :

• Consulter l'historique des livraisons (deliveries)
• Voir le statut de chaque livraison (succes, echec, timeout)
• Renvoyer une livraison qui a echoue

8.7 Tester un Webhook

Pour verifier que votre endpoint fonctionne correctement :

1. Dans la liste des webhooks, cliquez sur « Tester » a cote du webhook souhaite
2. Le systeme envoie un payload de test au endpoint configure
3. Le resultat (succes ou erreur) est affiche immediatement

---