Les webhooks envoient des notifications HTTP automatiques à votre serveur lorsque des événements se produisent dans votre compte Allo — un appel se termine, un SMS arrive, un contact est créé, et plus encore.
Ce que vous pouvez faire avec les webhooks
- Enregistrer les appels et messages dans votre CRM ou base de données
- Déclencher des workflows lorsque les appels se terminent ou que des SMS arrivent
- Synchroniser les contacts avec des systèmes externes
- Construire des tableaux de bord et alertes en temps réel
Événements disponibles
| Événement | Description |
|---|---|
call.received | Appel entrant commence à sonner |
call.triggered | Appel sortant initié |
call.answered | Appel décroché de l'autre côté |
call.completed | Appel terminé avec enregistrement, transcription et résumé |
tag.added | Tag ajouté à un appel |
tag.removed | Tag supprimé d'un appel |
sms.received | SMS entrant reçu |
sms.sent | SMS sortant envoyé |
contact.created | Contact créé |
contact.updated | Contact mis à jour |
Comment configurer les webhooks
Obtenir une clé API
Allez dans Paramètres > API et créez une clé API avec le scope WEBHOOKS_READ_WRITE.
Créer un endpoint webhook
curl -X POST https://api.withallo.com/v2/webhooks \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/allo",
"topics": ["call.completed", "sms.received"]
}'
Traiter les requêtes entrantes
Votre serveur reçoit une requête POST pour chaque événement. Retournez un code de statut 200 dans les 20 secondes pour confirmer la réception.
Vérifier les signatures
Chaque webhook inclut une signature cryptographique. Vérifiez-la pour vous assurer que la requête provient d'Allo. Voir Vérification des signatures.
Ouvrir les intégrations
Allez dans Paramètres > Intégrations > Webhooks dans l'application mobile Allo.
Activer les webhooks
Activez le switch webhook.
Configurer votre URL
Entrez l'URL HTTPS de votre endpoint. L'URL doit être accessible publiquement.
Sélectionner les événements
Choisissez les événements que vous souhaitez recevoir.
Tester la connexion
Appuyez sur Tester pour envoyer un événement de test à votre endpoint et vérifier qu'il fonctionne.
Format du payload webhook
Chaque webhook utilise la même enveloppe :
{
"topic": "call.completed",
"version": "2.0",
"timestamp": "2025-03-15T14:45:00.000Z",
"data": {
"id": "cll_2NfDKEm9sF8xK3pQr1Zt",
"from_number": "+33612345678",
"to": "+33112345678",
"type": "INBOUND",
"result": "ANSWERED",
"summary": "Le client a appelé pour une question de facturation.",
"recording_url": "https://storage.withallo.com/recordings/abc123.mp3"
}
}
Pour la spécification complète des payloads de chaque événement, voir le Catalogue des événements.
Sécurité
- L'URL de votre endpoint doit utiliser HTTPS.
- Chaque webhook inclut une signature cryptographique dans l'en-tête
webhook-signature. Vérifiez-la pour vous assurer que la requête est authentique. - Conservez votre secret de signature de manière sécurisée — traitez-le comme un mot de passe.
Fiabilité
- Allo réessaie les livraisons échouées jusqu'à 8 fois sur environ 27,5 heures avec un backoff exponentiel.
- Si votre endpoint échoue de façon continue pendant 5 jours, il est automatiquement désactivé.
- Vous pouvez récupérer les événements manqués en les rejouant après avoir corrigé votre endpoint.
Voir Livraison et nouvelles tentatives pour le calendrier complet des réessais.
Exemples d'implémentation
const express = require("express");
const app = express();
app.post(
"/webhooks/allo",
express.raw({ type: "application/json" }),
(req, res) => {
const event = JSON.parse(req.body);
switch (event.topic) {
case "call.completed":
console.log("Appel terminé :", event.data.id);
break;
case "sms.received":
console.log("SMS de :", event.data.from_number);
break;
}
res.sendStatus(200);
}
);
app.listen(3000);
from flask import Flask, request
app = Flask(__name__)
@app.route("/webhooks/allo", methods=["POST"])
def handle_webhook():
event = request.get_json()
if event["topic"] == "call.completed":
print(f"Appel terminé : {event['data']['id']}")
elif event["topic"] == "sms.received":
print(f"SMS de : {event['data']['from_number']}")
return "", 200
Dépannage
Le webhook ne reçoit pas d'événements
Vérifiez que votre endpoint est accessible publiquement via HTTPS. Vérifiez que le webhook est activé et abonné aux bons types d'événements. Utilisez l'endpoint de test pour vérifier.
Erreurs de timeout
Votre endpoint doit répondre dans les 20 secondes. Retournez 200 immédiatement et traitez l'événement en arrière-plan.
Réception d'événements en double
C'est attendu — Allo garantit une livraison « au moins une fois ». Utilisez l'en-tête webhook-id pour dédupliquer. Voir Bonnes pratiques.
La vérification de signature échoue
Assurez-vous d'utiliser le corps brut de la requête (pas le JSON parsé) pour la vérification. Vérifiez que votre secret de signature est correct et que l'horloge de votre serveur est précise. Voir Vérification des signatures.
Besoin d'aide ?
Documentation complète des webhooks API
Obtenir de l'aide de l'équipe Allo