Aller au contenu principal

Webhooks

Les webhooks permettent à Palisade d’avertir vos propres systèmes dès que quelque chose change, au lieu que vous deviez demander sans cesse si quelque chose a changé. Enregistrez une URL HTTPS, et Palisade y envoie un petit message JSON chaque fois qu’un domaine est ajouté, retiré ou change d’état.

Si votre système de gestion des billets est Autotask, ConnectWise ou HaloPSA, une intégration PSA vous conviendra sans doute mieux : elles sont conçues pour cela et ne demandent aucun code. Les webhooks sont la voie à suivre lorsque vos outils sont autres : un tableau de bord interne, un flux de travail Slack, un portail sur mesure ou une plateforme d’automatisation comme Zapier ou Make.

Ce à quoi vous pouvez vous abonner​

ÉvénementSe déclenche lorsque
domain.createdUn domaine est ajouté à votre organisation
domain.updatedUn domaine change : état de surveillance, score ou configuration
domain.deletedUn domaine est retiré
domain.monitoring.activatedUn domaine atteint pour la première fois la surveillance DMARC complète
domain.monitoring.failedLa surveillance n’a pas pu être établie, ou a été perdue
domain.monitoring.driftedUn domaine fonctionnel cesse de résoudre les enregistrements attendus
domain.monitoring.recoveredUn domaine en dérive ou en échec fonctionne de nouveau
domain.hosted_record.ready / .errorUn enregistrement hébergé par Palisade est entré en service, ou s’est brisé
domain.score_changedUn domaine a changé de tranche de score
domain.policy_changedLa politique DMARC a changé, par exemple de none à quarantine
mta_sts.enabled / .updated / .disabledMTA-STS hébergé change pour un domaine
task.opened / .completed / .canceled / .dismissed / .reopenedUne tâche de correction change d’état
organization.updated, member.*, invitation.*, group.*Changements touchant l’équipe et le compte

Si vous ne vous abonnez qu’à une seule chose, que ce soit domain.monitoring.drifted : un domaine qui cesse silencieusement de s’authentifier est la défaillance qui vous coûte cher. domain.monitoring.activated et .recovered en sont les bonnes nouvelles correspondantes, et domain.updated se déclenche toujours à chaque changement si vous préférez comparer vous-même.

La liste à jour est toujours accessible par l’API à GET /webhook-events.

Le contenu d’un message​

data.object est la ressource touchée, telle qu’elle était au moment de l’événement. Les événements qui décrivent un changement portent aussi data.previous_attributes avec les anciennes valeurs : vous n’avez donc pas à conserver votre propre copie de chaque domaine pour savoir ce qui a bougé. domain.score_changed, par exemple, vous indique la tranche d’où vous venez. Les événements d’enregistrements hébergés ajoutent data.record, qui indique lequel de dmarc, spf, dkim, bimi ou mta_sts a changé.

En configurer un​

  1. Créez un point de terminaison avec POST /webhook-endpoints, en indiquant l’URL à laquelle envoyer les événements.
  2. Conservez le secret de signature fourni dans la réponse. Il n’est affiché qu’une seule fois. Si vous le perdez, renouvelez-le pour en obtenir un nouveau.
  3. Vérifiez la signature de chaque requête reçue avant de vous y fier.

Le détail complet des requêtes et des réponses, ainsi que du code de vérification en Node et en Python, se trouve dans le guide de l’API.

attention

Quiconque connaît l’URL de votre point de terminaison peut y envoyer une requête. C’est la signature qui prouve qu’un message provient bel et bien de Palisade : vérifiez-la toujours, et n’agissez jamais sur un contenu non vérifié.

À quoi s’attendre en pratique​

Le même événement peut arriver deux fois. Palisade relance les livraisons qui échouent, et une relance peut arriver après que l’original a fini par réussir. Chaque message porte un id qui reste le même d’une relance à l’autre : notez les identifiants déjà traités et ignorez les doublons.

Les événements peuvent arriver dans le désordre. Si une livraison est relancée, un événement plus ancien peut arriver après un plus récent. Fiez-vous aux horodatages du contenu plutôt qu’à l’ordre d’arrivée pour savoir ce qui s’est passé.

Répondez rapidement. Répondez avec un code 2xx en moins de 10 secondes, et faites le vrai travail ensuite. Une réponse lente compte comme un échec et sera relancée.

Les points de terminaison qui échouent sans arrêt sont désactivés. Après 20 échecs consécutifs, le point de terminaison passe à AUTO_DISABLED et cesse de recevoir des événements jusqu’à ce que vous le réactiviez. Cela protège votre système contre un arriéré, et le nôtre contre des relances dans le vide.

Certains changements ne sont pas instantanés. Les états de surveillance des domaines proviennent d’un balayage périodique, et non d’un flux en direct : il y a donc un délai entre une modification DNS et l’événement qui la décrit. Le rétablissement après une erreur d’enregistrement hébergé est détecté par une réconciliation horaire : la disparition d’une error peut donc prendre une heure ou plus à être signalée.

Les événements de tâches attendent quatre heures, et c’est voulu. Les tâches nouvellement détectées fluctuent : une tâche doit donc garder son état pendant quatre heures avant que Palisade envoie un événement. Une tâche que vous voyez déjà dans le tableau de bord peut ne pas encore avoir produit de task.opened, et une tâche qui s’ouvre et se règle à l’intérieur de cette fenêtre ne produit aucun événement. C’est délibéré : cela garde hors de votre file de billets les problèmes qui se règlent d’eux-mêmes. Si vous préférez tout voir immédiatement, interrogez plutôt l’API des tâches.

conseil

Abonnez-vous à task.reopened en plus de task.completed. Si vous fermez un billet lorsqu’une tâche est terminée sans écouter sa réouverture, votre billet restera fermé après le retour du problème.

Vérifier ce qui s’est passé​

GET /webhook-endpoints/{id}/deliveries énumère les tentatives récentes, avec le code de réponse et l’erreur de chacune. Les données sont conservées 30 jours : c’est un outil de débogage plutôt qu’une archive. Si vous avez besoin d’un historique permanent, conservez les événements à mesure que vous les recevez. Vous pouvez encore consulter l’historique après avoir supprimé un point de terminaison, ce qui est habituellement précisément le moment où vous en avez besoin. Commencez par là lorsqu’un événement attendu n’est jamais arrivé : vous y trouverez généralement une signature refusée, un délai dépassé ou un point de terminaison désactivé.

Renouveler le secret​

POST /webhook-endpoints/{id}/rotate-secret émet un nouveau secret de signature et ne le retourne qu’une seule fois.

Le renouvellement prend effet immédiatement : les messages signés avec l’ancien secret échoueront à la vérification dès ce moment. Mettez à jour votre récepteur pendant la même fenêtre de changement, ou acceptez brièvement l’un ou l’autre secret pendant la transition.