Webhooks
Les événements, le contenu d'un message, la vérification de la signature, les nouvelles tentatives et les messages en double.
Avec un webhook, INTEGALL envoie un message POST à votre adresse dès qu'un événement se produit. L'entreprise de transport configure les webhooks dans le panneau entreprise (Clés API et webhooks) et vous transmet le secret de signature (whsec_…), qui n'est affiché qu'une seule fois.
Événements#
| Événement | Quand |
|---|---|
shipment.status_changed | Le statut d'un envoi (trajet) change. |
invoice.finalized | Une facture ou une note de crédit devient définitive. |
invoice.paid | Une facture définitive est marquée comme payée. |
ping | Un message de test envoyé depuis le panneau (Envoyer un message de test). |
Les données d'exemple du panneau ne déclenchent jamais de webhook.
Le message#
POST /integall HTTP/1.1
Content-Type: application/json
User-Agent: INTEGALL-Webhooks/1.0
X-INTEGALL-Event: shipment.status_changed
X-INTEGALL-Delivery: 1042
X-INTEGALL-Signature: t=1795000000,v1=5f2b…{
"id": 1042,
"event": "shipment.status_changed",
"at": "2026-11-18T09:05:00Z",
"shipment": {
"id": "ex-0001",
"ref": "RR-26-0003",
"from_status": "loading",
"status": "transit",
"changed_at": "2026-11-18T09:05:00Z"
}
}Pour invoice.finalized et invoice.paid, le message contient, à la place de shipment, un objet invoice avec id, number, type, customer_id, issue_date, due_date, net et paid_date. Pour ping, il contient "test": true.
Vérifier la signature#
L'en-tête X-INTEGALL-Signature a la forme t=<secondes-unix>,v1=<signature>. La signature est le HMAC-SHA256 (hexadécimal) du texte <t>.<corps brut> calculé avec votre secret whsec_.
- Lisez
tetv1dans l'en-tête. - Calculez le HMAC-SHA256 de
t + "." + corps brutavec votre secret. - Comparez le résultat à
v1avec une comparaison en temps constant. - Refusez le message si
tdate de plus de 5 minutes.
Exemple en Python :
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, sig = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)Utilisez le corps brut tel que reçu, et non un JSON remis en forme.
Réponses et nouvelles tentatives#
- Répondez dans les 10 secondes avec un statut
2xx. Traitez les tâches lourdes ensuite, pas pendant la réponse. - Les redirections (
3xx) ne sont pas suivies et comptent comme des échecs. - Une livraison échouée est retentée après 1, 5 et 15 minutes, puis 1, 3, 8 et 16 heures : 8 tentatives, environ 28 heures.
- Un message qui n'est pas arrivé après toutes les tentatives peut être renvoyé par l'entreprise depuis le panneau (Renvoyer les échecs, les 7 derniers jours).
- Si votre adresse ne répond pas pendant plus de 24 heures d'affilée, le webhook est désactivé automatiquement.
Messages en double#
Un message peut arriver plus d'une fois. Utilisez le champ id du corps (aussi dans X-INTEGALL-Delivery) pour reconnaître les messages en double et ne les traiter qu'une seule fois.
Exigences pour votre adresse#
- Uniquement
https, sur le port 443, sans nom d'utilisateur ni mot de passe dans l'adresse. - Un nom de domaine public, pas d'adresse IP. Les adresses qui pointent vers un réseau interne sont refusées.
- Au maximum 10 webhooks par entreprise.