Configurer une destination
Vous configurez les webhooks d’alertes dans la Business Console, et non via l’API. Les membres qui peuvent gérer les paramètres de l’organisation peuvent ajouter, modifier et tester des destinations.1
Ajouter la destination
Dans Paramètres de l’organisation > Notifications de l’équipe, ajoutez une destination Webhook d’alertes avec l’URL de votre endpoint.
L’URL doit utiliser
https:// et pointer vers une adresse publique.2
Conserver le secret de signature
Didit n’affiche le secret de signature complet, commençant par
whsec_, qu’une seule fois.
Enregistrez-le dès maintenant : la console n’affichera ensuite que ses quatre derniers caractères.3
Y acheminer les alertes
L’ajout d’une destination n’envoie encore rien vers celle-ci.
Ajoutez la destination aux règles de routage des alertes que vous souhaitez lui faire recevoir.
4
Envoyer un test
Cliquez sur Envoyer un test pour envoyer une alerte
alert.test, et vérifiez que votre endpoint l’accepte.Types d’alertes
Payload
Chaque alerte est unPOST avec un corps en JSON.
Didit envoie le corps sous forme de JSON compact avec ses clés triées.
Cet exemple est mis en forme pour en faciliter la lecture :
data contient toujours :
event: la clé de l’événement, par exemplesession_in_review.labeletvalue: l’objet de l’alerte, par exempleSessionet#1042.
data :
alert.billing.autorefill_failedajoutepaused, un booléen valanttruelorsque la recharge automatique est suspendue jusqu’à ce que vous mettiez à jour la carte.alert.service.degradedetalert.service.recoveredajoutentservice,status,incident_id,service_name,state,affected,country_name,started_at,resolved_at,duration_minutes,titleetbody.statusvautdegradedoudownpouralert.service.degraded, etrecoveredpouralert.service.recovered.serviceutilise les clés de service deGET /v3/status/, etincident_idcorrespond à unidd’incident sur cet endpoint.
webhook_type et les clés de data que vous ne reconnaissez pas, afin que les nouveaux éléments n’interrompent pas votre endpoint.
En-têtes de requête
Vérifier la signature
X-Signature-V2 est le HMAC-SHA256 encodé en hexadécimal de la chaîne <X-Timestamp>.<raw body>, calculé avec le secret de signature de votre destination.
- Utilisez le secret complet exactement tel que Didit l’a affiché, y compris le préfixe
whsec_. - Signez les octets bruts de la requête tels que vous les avez reçus. Parser le JSON et le sérialiser à nouveau peut modifier les octets et faire échouer la vérification.
- Comparez les signatures en temps constant.
- Rejetez toute requête dont le
X-Timestampprésente un écart de plus de 5 minutes avec votre horloge. Didit signe chaque tentative, y compris chaque nouvel essai, avec un horodatage récent, de sorte que cette fenêtre ne rejette jamais une nouvelle tentative légitime. - Répondez à un échec de vérification avec le code
400. Une réponse401,403,404ou410marque la destination comme nécessitant une reconnexion (voir Nouvelles tentatives).
Node.js (Express)
Python (Flask)
Renouveler le secret de signature
Vous renouvelez le secret sur la destination dans Notifications de l’équipe. Didit affiche le nouveau secret une seule fois et signe toutes les tentatives ultérieures avec celui-ci, y compris les nouvelles tentatives d’alertes créées avant le renouvellement. L’ancien secret cesse immédiatement de fonctionner. Il n’y a pas de période de chevauchement, et aucun en-tête ne porte de signature générée avec le secret précédent. Déployez le nouveau secret sur votre endpoint dès que vous le renouvelez.Nouvelles tentatives
Didit considère toute réponse2xx comme livrée.
Didit attend votre réponse jusqu’à 5 secondes pour chaque tentative et ne suit pas les redirections.
Didit réessaie d’envoyer une alerte après l’expiration du délai d’attente, un échec de connexion, une réponse 5xx, ou une réponse 408, 425 ou 429.
Le système effectue jusqu’à 5 nouvelles tentatives, réparties sur environ 24 heures :
Toute autre réponse est définitive, y compris les codes
3xx et tout autre code 4xx.
Un test envoyé avec Envoyer un test fait l’objet d’une seule tentative et n’est jamais réessayé.
Une réponse 401, 403, 404 ou 410 marque également la destination comme nécessitant une reconnexion : la console l’affiche avec l’état Reconnecter.
Il en va de même pour une URL qui renvoie vers une adresse privée ou autrement bloquée au moment de l’envoi par Didit.
Didit continue d’envoyer de nouvelles alertes à la destination, et celle-ci redevient active après la prochaine livraison réussie ou lorsque vous mettez à jour son URL.
La section Notifications récentes dans Notifications de l’équipe liste chaque livraison avec son résultat, et vous pouvez relancer une livraison ayant échoué à partir de là.
Voir aussi
- Webhooks de vérification : résultats de session, d’entité et de transaction pour votre application.
- État du service : le flux public associé à
alert.service.degradedetalert.service.recovered. - Examen manuel : que faire lorsqu’une vérification est en cours d’examen.