Webhooks

Un webhook envoie une requête HTTPS à votre serveur au moment même où quelque chose se produit dans votre espace de travail. Utilisez les webhooks plutôt que d'interroger l'API en boucle : lorsqu'un appel se termine, vous recevez immédiatement le résumé, le résultat, les détails collectés et la transcription. Chaque livraison est signée avec un secret que seuls vous et Ringhum connaissez, afin que votre serveur puisse rejeter tout ce qui ne vient pas de Ringhum.

Ajouter un point de terminaison

Seuls le Propriétaire et les Admins de l'espace de travail peuvent ajouter, tester et retirer des points de terminaison.

1. Ouvrez Développeurs dans la barre latérale.
2. Dans la carte Webhooks, cliquez sur Ajouter un endpoint.
3. Saisissez l'URL de l'endpoint. Elle doit commencer par https://.
4. Sous Événements, cochez les événements souhaités. call.ended est coché pour vous.
5. Cliquez sur Ajouter un endpoint.
6. Copiez le secret de signature depuis l'encadré vert (il commence par whsec_) et stockez-le sur votre serveur. Cliquez sur Terminé.

Important : le secret de signature n'est affiché qu'une seule fois. Si vous le perdez, retirez le point de terminaison et ajoutez-le à nouveau pour obtenir un nouveau secret.

Vous pouvez ajouter autant de points de terminaison que nécessaire. Les webhooks couvrent chaque assistant de l'espace de travail. Vous pouvez aussi gérer les points de terminaison via l'API, avec POST /webhooks et une clé ayant la portée write.

Événements

À quoi ressemble une livraison

Chaque livraison est une requête POST avec un corps JSON et ces en-têtes :

POST https://example.com/hooks/ringhum
Content-Type: application/json
User-Agent: Ringhum-Webhooks/1.0
X-Ringhum-Event: call.ended
X-Ringhum-Timestamp: 1789250000
X-Ringhum-Signature: v1=5f1a…

{
  "id": "evt_8f2k…",
  "type": "call.ended",
  "created_at": "2026-09-24T14:03:11+00:00",
  "data": {
    "call_id": 4812,
    "direction": "inbound",
    "from": "+14155550132",
    "to": "+14155550100",
    "assistant_id": 3,
    "status": "completed",
    "outcome": "message_taken",
    "sentiment": "neutral",
    "duration_seconds": 94,
    "summary": "Caller asked for a quote for a kitchen repair…",
    "extracted": { "name": "Dana Lee", "reason": "Quote" },
    "transcript": [
      { "role": "assistant", "content": "Hello, you've reached…" },
      { "role": "user", "content": "Hi, I'd like a quote…" }
    ]
  }
}

L'objet data dépend de l'événement :

• call.ended et message.taken : les champs d'appel ci-dessus.
• call.started et call.transferred : call_id, direction, from, to, assistant_id, status et started_at.
• appointment.* : appointment_id, title, status, starts_at, ends_at, timezone, customer (nom, téléphone, e-mail), contact_id, service, staff, call_id et notes.
• order.* : order_id, number, status, fulfillment, customer, address, items avec options et prix, currency, subtotal, fee, total, source, call_id et, pour les annulations, cancel_reason.
• reservation.* : reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total et source.
• campaign.completed : campaign_id, name et les compteurs de progression de la campagne.

Remarque : lorsque l'assistant prend un rendez-vous pendant un appel, vous pouvez recevoir appointment.booked deux fois. La première est envoyée au moment de la prise du rendez-vous, avec les champs du rendez-vous. La seconde est envoyée après le résumé de l'appel, avec les champs de l'appel. Vérifiez si data contient appointment_id ou call_id et utilisez le champ id pour éviter de traiter deux fois la même livraison.

Vérifier la signature

La signature est un HMAC-SHA256 de l'horodatage, d'un point, et du corps brut de la requête, signé avec le secret de votre point de terminaison. Elle est envoyée sous la forme v1= suivi de l'empreinte hexadécimale.

1. Lisez le corps brut exactement tel que reçu, avant toute analyse JSON.
2. Construisez la chaîne {X-Ringhum-Timestamp}.{corps brut}.
3. Calculez le HMAC-SHA256 avec votre secret et préfixez-le avec v1=.
4. Comparez-le à X-Ringhum-Signature avec une comparaison en temps constant.
5. Rejetez la requête si l'horodatage a plus de cinq minutes, afin de bloquer les requêtes rejouées.

Node.js :

const crypto = require('crypto');

function isValid(req, rawBody, secret) {
  const ts = req.header('X-Ringhum-Timestamp');
  const sig = req.header('X-Ringhum-Signature') || '';
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

PHP :

$ts = $_SERVER['HTTP_X_RINGHUM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_RINGHUM_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

Réponses, délais d'expiration et nouvelles tentatives

• Répondez avec un statut 2xx pour confirmer la livraison. Effectuez les traitements longs après avoir répondu.
• Ringhum attend jusqu'à 10 secondes votre réponse.
• Si votre point de terminaison ne répond pas avec un 2xx, la livraison est retentée jusqu'à 3 fois au total : immédiatement, à nouveau environ 10 secondes plus tard, puis une dernière fois environ 60 secondes après. Passé cela, elle est abandonnée.
• Les livraisons peuvent arriver dans le désordre. Utilisez created_at et les identifiants dans data pour les remettre en ordre.

Le tableau Webhooks affiche le dernier statut HTTP de chaque point de terminaison et le moment de l'envoi. Un point de terminaison en échec reste actif ; Ringhum ne le désactive pas pour vous.

Tester, mettre en pause et retirer

• Envoyer un test envoie immédiatement un événement test.ping, et un message affiche le statut HTTP renvoyé par votre point de terminaison.
• L'interrupteur Actif met en pause un point de terminaison. Les événements survenant pendant la pause ne sont pas envoyés plus tard.
• Retirer supprime le point de terminaison et son secret.

Questions courantes

Quelle est la différence avec les applications Zapier, Make et n8n sous Intégrations ? Ces connexions utilisent la page Intégrations et ses six types d'événements. Leur corps est {"event", "workspace", "sent_at", "data"}, et lorsque vous définissez un secret, l'en-tête de signature est X-Ringhum-Signature: sha256=…, un HMAC-SHA256 du corps seul. Les webhooks développeurs décrits ici couvrent plus d'événements et utilisent la signature v1= avec un horodatage. Voir Choisir ce qui est envoyé.

Mon point de terminaison renvoie 2xx mais mon code ne voit rien. Vérifiez que l'événement est coché pour ce point de terminaison, qu'il est actif, et que votre pare-feu autorise les requêtes venant d'internet.

Pourquoi la vérification de signature échoue-t-elle ? Le plus souvent, le corps a été analysé puis réencodé avant le hachage. Hachez les octets bruts exactement tels que reçus.