Les webhooks

Un webhook previent un autre systeme, le votre ou un outil comme n8n, Make ou Zapier, au moment ou quelque chose se passe dans Magnitude : un dossier s'ouvre, change, se resout. Vous n'avez rien a interroger : l'evenement vous est livre, signe, a l'adresse que vous avez donnee.

Declarer un point de livraison

Dans Reglages, Webhooks, ajoutez une adresse en HTTPS (une adresse en clair est refusee : un secret et des donnees client ne partent pas sur un canal non chiffre) et cochez les evenements qui vous interessent. A la creation, le produit vous montre le secret du point de livraison une seule fois. Copiez-le dans votre systeme : il ne sera jamais raffiche, et il sert a verifier que ce que vous recevez vient bien de nous.

Les evenements

D'autres noms existent dans la liste (conversation.*, contact.*, message.*) : ils sont reserves et ne partent pas encore. Ne construisez rien dessus aujourd'hui ; cette page dira le jour ou ils partent.

Ce que vous recevez

Une requete POST, corps JSON, avec trois en-tetes :

Le corps :

{
  "id": "a01ae3e8-…",
  "type": "ticket.created",
  "data": {
    "id": "04163729-…", "number": 11,
    "subject": "Echange d'un velo de montagne arrive avec le cadre raye",
    "description": "…",
    "status": "open", "status_label": null, "priority": "high",
    "type_id": "fc0c1209-…",
    "custom": { "product": "mtb", "order_number": "TB-7788" },
    "origin": "ai", "channel": "website",
    "requester_contact_id": "e645f0…", "conversation_id": null,
    "assignee_user_id": null, "team_id": null,
    "resolution_code": null, "cause_code": null,
    "created_at": "2026-09-03T01:10:17.212Z", "updated_at": "2026-09-03T01:10:17.212Z"
  }
}

custom porte les champs metier du type, par leur cle (celle que vous voyez dans Reglages, Types de dossier). origin dit qui a ouvert le dossier : agent (un membre), ai (l'agent IA), customer (un client, par exemple le panier du site), api ou external (un autre systeme).

Verifier la signature

La signature est un HMAC SHA-256, avec votre secret, de la chaine identifiant.horodatage.corps (les trois valeurs separees par un point, le corps tel qu'il est recu, octet pour octet), encode en base64. Recalculez-la et comparez : si elle differe, ignorez la requete. C'est la convention Standard Webhooks, que la plupart des bibliotheques savent verifier telle quelle.

Ce qui se passe si votre systeme ne repond pas

Une reponse autre que 2xx, ou pas de reponse, est un echec. Le produit reessaie, avec des attentes qui s'allongent : tout de suite, puis 1 minute, 5 minutes, 30 minutes, 2 heures, 10 heures. Au bout de vingt echecs de suite, le point de livraison se desactive tout seul : une file qui reessaie sans fin un point mort devient elle-meme la panne. Vous le reactivez dans Reglages, Webhooks, une fois votre systeme repare.

L'essayer en cinq minutes

1. Ouvrez une adresse de test : n8n (un nœud Webhook en mode test), ou un service comme webhook.site, vous donne une adresse HTTPS qui affiche ce qu'elle recoit.
2. Declarez-la dans Reglages, Webhooks, avec ticket.created et ticket.updated.
3. Ouvrez un dossier (a la main, depuis une conversation, ou en le demandant a l'agent de votre site), puis changez sa priorite.
4. Regardez arriver les deux requetes, avec leurs en-tetes.

Ce qui n'existe pas encore

• Les evenements de conversation, de contact et de message ne partent pas (voir plus haut).
• Pas de rejeu a la demande : un evenement manque pendant une panne de votre cote est reessaye selon le calendrier ci-dessus, pas plus.
• Pas de filtre par type de dossier ni par equipe : un point de livraison recoit tous les dossiers de l'espace pour les evenements qu'il a coches.