Webhooks

Les événements, le contenu d'un message, la vérification de la signature, les nouvelles tentatives et les messages en double.

Dernière mise à jour: Besoin d'aide ? Contactez le support

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énementQuand
shipment.status_changedLe statut d'un envoi (trajet) change.
invoice.finalizedUne facture ou une note de crédit devient définitive.
invoice.paidUne facture définitive est marquée comme payée.
pingUn 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_.

  1. Lisez t et v1 dans l'en-tête.
  2. Calculez le HMAC-SHA256 de t + "." + corps brut avec votre secret.
  3. Comparez le résultat à v1 avec une comparaison en temps constant.
  4. Refusez le message si t date 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.