À propos des webhooks
Comment fonctionnent les callbacks, les abonnements, les signatures et les nouvelles tentatives quand la plateforme envoie des événements à votre endpoint.
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
| Objet | Ce qu'il fait | Ce que vous définissez |
|---|---|---|
| Callback | Indique où partent les requêtes et quelle forme elles prennent | URL HTTPS, mode d'authentification, secret de signature, transformation de requête facultative |
| Abonnement | Indique quels événements atteignent un callback | Types 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
POSTavecContent-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ête | Ce qu'il contient | Comment l'utiliser |
|---|---|---|
webhook-id | msg_, 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-timestamp | L'horodatage Unix, en secondes, de la signature de cette tentative. Chaque tentative a le sien. | Rejetez les requêtes trop anciennes |
webhook-signature | Une ou deux signatures v1,<base64>, séparées par un espace | Vérifiez la signature avant tout traitement |
User-Agent | OmniLab-Webhook/1.0 | Journaux et listes d'autorisation |
Garanties de livraison
| Situation | Ce que fait la plateforme |
|---|---|
Votre endpoint répond 2xx | Marque la livraison comme réussie. |
5xx, 429, une redirection (3xx), une erreur réseau, ou aucune réponse sous 30 secondes | Réessaie, jusqu'à 5 fois après la première tentative. Les redirections ne sont jamais suivies. |
| Délai entre les tentatives | Attend 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éponse | L'ignore. Les nouvelles tentatives suivent le calendrier ci-dessus. |
Tout autre 4xx | S'arrête. L'échec est définitif et l'événement n'est pas retenté. |
410 Gone | S'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 OAuth2 | Ré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 échoue | S'arrête. L'échec est définitif. |
| La dernière tentative échoue | Abandonne l'événement pour ce callback. Il n'est pas renvoyé. |
| Plusieurs événements à la suite | Les 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 Ko | Ne le livre pas. |
| Connexion à votre endpoint | Utilise 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é :
webhook-id + "." + webhook-timestamp + "." + raw_request_bodyLe 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-timestampest récent.
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.