À propos des webhooks

Comment fonctionnent les callbacks, les abonnements, les signatures et les nouvelles tentatives quand la plateforme envoie des événements à votre endpoint.

3 min de lecture

Chaque événement, comme un lot gagné ou une réservation effectuée, vous parvient sous la forme d'une requête HTTPS signée. Votre récepteur la vérifie, ignore les doublons et répond vite.

Callbacks et abonnements

ObjetCe qu'il faitCe que vous définissez
CallbackIndique où partent les requêtes et quelle forme elles prennentURL HTTPS, mode d'authentification, secret de signature, transformation de requête facultative
AbonnementIndique quels événements atteignent un callbackTypes d'événements, filtres facultatifs, statut Actif ou En pause

Un callback peut avoir plusieurs abonnements. Quand plusieurs d'entre eux correspondent à un même événement, le callback ne reçoit malgré tout qu'une seule requête.

Contenu de chaque requête

  • POST avec Content-Type: application/json, sauf si la transformation du callback les modifie.
  • L'événement sous la forme d'un document JSON CloudEvents, sauf si un modèle de corps le remplace. La référence des événements montre une requête complète.
  • Ces en-têtes :
En-têteCe qu'il contientComment l'utiliser
webhook-idmsg_, puis l'ID de l'événement et l'ID du callback. Il reste identique à chaque nouvelle tentative.Stockez-le et ignorez les doublons
webhook-timestampL'horodatage Unix, en secondes, de la signature de cette tentative. Chaque tentative a le sien.Rejetez les requêtes trop anciennes
webhook-signatureUne ou deux signatures v1,<base64>, séparées par un espaceVérifiez la signature avant tout traitement
User-AgentOmniLab-Webhook/1.0Journaux et listes d'autorisation

Garanties de livraison

SituationCe que fait la plateforme
Votre endpoint répond 2xxMarque la livraison comme réussie.
5xx, 429, une redirection (3xx), une erreur réseau, ou aucune réponse sous 30 secondesRéessaie, jusqu'à 5 fois après la première tentative. Les redirections ne sont jamais suivies.
Délai entre les tentativesAttend environ 0,5, 1, 2, 4 et 8 secondes : 15,5 secondes au total, plus la durée de chaque tentative.
Un en-tête Retry-After dans votre réponseL'ignore. Les nouvelles tentatives suivent le calendrier ci-dessus.
Tout autre 4xxS'arrête. L'échec est définitif et l'événement n'est pas retenté.
410 GoneS'arrête, et fait passer le callback au statut En échec. Il ne reçoit plus rien. Voir Surveiller l'état des livraisons.
401 d'un endpoint qui utilise OAuth2Récupère un nouveau jeton et réessaie une fois, immédiatement. Un second 401 est définitif.
Votre endpoint de jeton OAuth2 ne renvoie aucun jeton, ou le rendu d'un modèle échoueS'arrête. L'échec est définitif.
La dernière tentative échoueAbandonne l'événement pour ce callback. Il n'est pas renvoyé.
Plusieurs événements à la suiteLes envoie sans ordre garanti. Utilisez le champ time de chaque événement pour les remettre dans l'ordre.
Un événement de plus de 256 KoNe le livre pas.
Connexion à votre endpointUtilise HTTPS avec TLS 1.2 ou supérieur, et uniquement vers des hôtes qui se résolvent en adresses IP publiques.

Vérifier la signature

La signature est un HMAC-SHA256 de cette chaîne exacte, calculé avec votre secret de signature, décodé du base64, comme clé :

Signed payload format
webhook-id + "." + webhook-timestamp + "." + raw_request_body

Le résultat est encodé en base64 et préfixé par v1,. Après un renouvellement du secret de signature, chaque livraison comporte deux signatures, séparées par un espace : l'une faite avec le nouveau secret, l'autre avec le précédent. Cela dure jusqu'au renouvellement suivant. Acceptez la requête dès que l'une d'elles correspond.

Deux points qu'un vérificateur naïf traite mal :

  • Comparer les signatures comme des chaînes. Une égalité de chaînes, ou un test d'appartenance à un tableau, laisse fuiter des informations de timing qu'un attaquant peut exploiter pour deviner la signature octet par octet. Utilisez une comparaison à temps constant.
  • Ignorer l'horodatage. Une signature seule n'empêche pas quelqu'un de rejouer plus tard une requête capturée. Vérifiez que webhook-timestamp est récent.
verify.js
import crypto from "node:crypto";

const MAX_TIMESTAMP_SKEW_SECONDS = 300; // 5 minutes

export function isValidOmniLabSignature({
  header,
  webhookId,
  webhookTimestamp,
  rawBody,
  signingSecret,
}) {
  // Rejette un horodatage trop ancien ou daté dans le futur, pour qu'un
  // callback capturé puis rejoué plus tard ne passe pas la vérification.
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(webhookTimestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > MAX_TIMESTAMP_SKEW_SECONDS) {
    return false;
  }

  const signedPayload = `${webhookId}.${webhookTimestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", Buffer.from(signingSecret, "base64"))
    .update(signedPayload)
    .digest();

  // Après un renouvellement du secret, l'en-tête contient deux paires
  // "v1,<signature>" : on vérifie chacune plutôt que l'en-tête entier.
  return header.split(" ").some((part) => {
    const [version, signature] = part.split(",");
    if (version !== "v1" || !signature) return false;

    let candidate;
    try {
      candidate = Buffer.from(signature, "base64");
    } catch {
      return false;
    }

    // timingSafeEqual lève une exception si les deux buffers n'ont pas la
    // même longueur : on écarte ce cas avant la comparaison à temps constant.
    return (
      candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected)
    );
  });
}

La section Recevoir votre premier événement intègre ce vérificateur dans un récepteur complet.

Étapes suivantes

Sur cette page