Configurer les webhooks

Même si la mise en place est aujourd'hui faite avec l'équipe OmniLab, votre équipe technique doit préparer un receiver robuste avant le go-live.

1. Préparer le receiver

Votre endpoint doit :

• être accessible en HTTPS public
• accepter le body brut sans le réécrire avant la vérification de signature
• répondre vite, puis déléguer le traitement lourd à une file ou un worker
• être idempotent en stockant webhook-id pour éviter les doublons de traitement

2. Choisir l'authentification sortante

Un callback OmniLab peut être configuré avec différents modes d'authentification sortante selon votre receiver :

• aucune authentification supplémentaire
• Basic
• Bearer
• OAuth 2.0 client credentials

La signature webhook reste utile même si une authentification sortante est aussi activée, car elle permet de vérifier l'intégrité du message lui-même.

3. Gérer la rotation du secret de signature

Le secret de signature d'un callback peut être régénéré. Pendant une fenêtre de rotation, OmniLab peut accepter l'ancien et le nouveau secret côté livraison afin de permettre une transition propre.

Côté receiver, le plus sûr est de :

• stocker un secret principal et un secret précédent pendant la fenêtre de rotation
• essayer la vérification avec le secret principal, puis avec le précédent si nécessaire
• retirer l'ancien secret une fois la rotation finalisée avec l'équipe OmniLab

import crypto from 'node:crypto';

function sign(secret, id, timestamp, rawBody) {
  return crypto
    .createHmac('sha256', secret)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest('base64');
}

function isValidSignature({ currentSecret, previousSecret, id, timestamp, rawBody, signature }) {
  const expected = [`v1,${sign(currentSecret, id, timestamp, rawBody)}`];

  if (previousSecret) {
    expected.push(`v1,${sign(previousSecret, id, timestamp, rawBody)}`);
  }

  return expected.includes(signature);
}

4. Gérer les retries et les statuts HTTP

Comportements à anticiper :

• 2xx : livraison considérée comme réussie
• 429 : retry possible, avec prise en compte de Retry-After lorsqu'il existe
• 5xx ou timeout : retry automatique à prévoir
• 4xx durable : échec non retryable dans la plupart des cas
• 410 Gone : callback désactivé pour signaler qu'il ne doit plus être utilisé

5. Préparer les transformations si nécessaire

Un callback peut aussi appliquer des templates Liquid à certains éléments de la livraison, notamment :

• le body de la requête
• l'URL cible
• certains headers personnalisés

C'est utile si votre receiver aval attend une forme de payload ou des headers spécifiques. Confirmez cependant ces besoins avant mise en place, car chaque transformation ajoute un peu de complexité à maintenir.

Checklist avant go-live

• URL receiver publique validée
• TLS et règles d'accès testés
• vérification de signature en place
• fenêtre de tolérance au replay définie
• stockage de webhook-id pour l'idempotence
• observabilité sur les 2xx, 4xx, 429, 5xx, et les timeouts
• procédure de rotation de secret documentée côté intégrateur

Pour aller plus loin