À propos des webhooks

Découvrez comment OmniLab transforme les événements produit en requêtes HTTPS sortantes, pour construire un receiver qui vérifie, déduplique et gère correctement les retries. Si vous préparez un receiver ou relisez une conception de webhook avec OmniLab, commencez ici.

Les deux objets qui comptent

Un même callback peut recevoir plusieurs abonnements. Les abonnements peuvent restreindre la livraison à un tenant, un groupe, ou une interaction, selon ce dont votre système aval a besoin.

Flux de livraison

Ce qu'OmniLab envoie par défaut

• Uniquement des requêtes HTTPS
• POST par défaut
• application/json par défaut
• L'événement source brut comme body de la requête, sauf si une transformation est configurée
• Des headers de livraison sur chaque requête
• Une taille maximale de payload brut de 256 KB par requête de livraison

OmniLab peut aussi transformer la méthode, l'URL, le content type, le body de la requête et les headers personnalisés lorsqu'un système aval attend une forme différente.

Headers à attendre

Modes d'authentification des callbacks sortants

OmniLab peut envoyer les callbacks avec l'une de ces stratégies d'authentification :

• Aucun header d'auth supplémentaire
• Basic auth
• Bearer auth, via Authorization ou un autre nom de header convenu
• OAuth 2.0 client credentials, où OmniLab échange d'abord le client ID et le secret du callback contre un access token

Si un receiver protégé par OAuth 2.0 renvoie 401, OmniLab peut retenter une fois après avoir rafraîchi l'access token.

Comportement de retry et gestion des échecs

• Les réponses 2xx sont considérées comme un succès.
• Les réponses 5xx, les échecs réseau transitoires, les timeouts et les réponses 429 sont retryables.
• Si votre receiver renvoie 429, OmniLab peut respecter le header Retry-After lorsqu'il est présent.
• Les réponses 4xx autres que 429 sont traitées comme des échecs permanents.
• Une réponse 410 Gone désactive le callback, de sorte que les événements ultérieurs cessent de générer des requêtes sortantes jusqu'à correction du callback.
• La même combinaison événement + callback est dédupliquée côté OmniLab, mais votre receiver doit tout de même être idempotent, car les retries peuvent réutiliser le même identifiant de livraison.

Signature et rotation de clé

OmniLab calcule la signature à partir de cette chaîne exacte :

webhook-id + "." + webhook-timestamp + "." + raw_request_body

La signature utilise HMAC-SHA256 et est renvoyée avec un préfixe v1,.

import crypto from "node:crypto";

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

  return header.split(" ").includes(expected);
}

Pendant la rotation du secret de signature, OmniLab peut envoyer la signature v1,... courante et la précédente dans le même header webhook-signature. Acceptez l'une ou l'autre valeur pendant la fenêtre de transition, puis retirez l'ancien secret de votre côté.

Pour aller plus loin