Webhooks

Webhooks let Kadryn deliver événements à vos systèmes.

Utilisez webhooks lorsque un externe service needs à react à Kadryn événements such as alerts, rapports, exports, delivery états, integration changes ou gouvernance activity.

Ce que vous pouvez faire

La page Webhooks vous permet de :

• créer webhook endpoints;
• subscribe endpoints à événement types;
• inspecter endpoint readiness;
• envoyer test webhooks;
• view recent deliveries;
• redeliver échoué événements;
• faire tourner webhook secrets;
• inspecter événement catalog entries;
• identifier failing ou quarantined endpoints.

Exigences endpoint

Un endpoint webhook doit :

• utiliser HTTPS;
• be reachable depuis Kadryn;
• vérifier Kadryn signatures;
• parser le JSON en sécurité;
• respond quickly;
• return 2xx seulement après accepting le événement;
• process heavy work asynchronously;
• be idempotent.

Créer un endpoint

Ouvrir :

Developers → Webhooks

Créez ensuite un endpoint avec :

• un name;
• un HTTPS URL;
• sélectionné événement types;
• active statut.

Kadryn peut show readiness as manquant, waiting pour delivery, degraded ou ready.

Abonnements aux événements

You peut subscribe un endpoint à one ou more événement types.

Si aucune sélection d’événements spécifique n’est configurée, votre workspace peut traiter l’endpoint comme abonné au catalogue par défaut. Préférez des abonnements explicites pour les endpoints production.

Tester la livraison

Utilisez un webhook de test lorsque :

• vous créez une new endpoint;
• vous faire tourner une secret;
• votre endpoint était en échec;
• vous change événement subscriptions;
• vous deploy un new recevoirr.

Après avoir envoyé un test, inspectez le résultat de livraison et les logs de l’endpoint.

États de livraison

États endpoint

Redelivery

Utilisez la redelivery lorsqu’une livraison échoue à cause d’un problème temporaire d’endpoint.

Before redelivering:

• fix le endpoint;
• vérifier signature verification;
• vérifier rate limits;
• vérifier événement handling est idempotent;
• passer en revue recent échecs.

Exemple de recevoirr

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyKadrynSignature(input: {
  readonly rawBody: string;
  readonly timestamp: string;
  readonly signature: string;
  readonly secret: string;
}): boolean {
  const payload = `${input.timestamp}.${input.rawBody}`;
  const expected = createHmac("sha256", input.secret)
    .update(payload)
    .digest("hex");

  const left = Buffer.from(input.signature, "hex");
  const right = Buffer.from(expected, "hex");

  return left.length === right.length && timingSafeEqual(left, right);
}

Utilisez le full verification guide avant deploying un recevoirr.

Règles de sécurité

Do:

• vérifier signatures;
• reject obsolète timestamps;
• keep webhook secrets côté serveur;
• faire tourner secrets après exposure;
• process événements idempotently;
• return quickly;
• log delivery IDs et événement IDs.

Do not:

• trust unsigned payloads;
• process événements avant verification;
• stocker webhook secrets dans client code;
• block le request while running long jobs;
• retry non-idempotent side effects sans un dedupe clé.

Dépannage

Endpoint stays manquant_endpoint

Créez au moins un endpoint HTTPS actif.

Readiness est waiting_for_delivery

Envoyez un test webhook ou wait pour un real événement.

Readiness est degraded

Inspect failing deliveries, réponse statut, latence, endpoint état et signature verification.

Deliveries keep failing

Vérifiez recevoirr logs, HTTPS availability, signature verification, réponse statut et processing time.

Pages liées

• Webhook signatures
• Erreurs
• Rate limits
• Échecs webhook