Sécurité

La fiabilité des webhooks dépend autant du comportement de votre endpoint que des garanties de livraison d'Unico. Cette page couvre les trois invariants que votre endpoint doit respecter : idempotence, limite de concurrence et taux d'erreur.

Idempotence

L'implémentation des webhooks d'Unico garantit une livraison au moins une fois — le même statut peut être notifié plus d'une fois pour le même processId. Votre endpoint doit être idempotent.

Modèle recommandé :

1. À chaque appel de webhook, vérifiez d'abord si processId a déjà été traité.
2. Si c'est le cas, retournez 2xx immédiatement (le traitement est déjà effectué).
3. Sinon, appliquez votre logique métier et enregistrez le fait que ce processId a été traité.

// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}

Pourquoi c'est important

Un endpoint non idempotent qui exécute une logique métier à chaque livraison (p. ex. débite une carte, envoie un e-mail) se déclenchera plusieurs fois en cas de nouvelle tentative — et les nouvelles tentatives sont normales, pas exceptionnelles, dans la livraison de webhooks.

Limite de concurrence

Pour protéger votre endpoint contre les pics de charge en période de fort volume, configurez un nombre maximum de livraisons simultanées en cours (max : 500) lors de l'enregistrement du webhook.

Lorsque la limite de concurrence est atteinte, Unico met les livraisons supplémentaires en file d'attente et les traite dès que la capacité est disponible. Combiné aux nouvelles tentatives, cela signifie qu'un pic soutenu peut prolonger le délai de livraison effectif des nouveaux webhooks.

Taux d'erreur

Le taux d'erreur (réponses hors de la plage 200–299) doit toujours rester faible. Si votre endpoint commence à retourner des erreurs à grande échelle, Unico réduit automatiquement le débit des webhooks pour cet endpoint. Combiné au mécanisme de nouvelle tentative, cela peut augmenter considérablement le temps d'exécution des nouveaux webhooks.

Conseils opérationnels :

• Surveillez les réponses non-2xx de votre côté. Déclenchez une alerte en cas de taux d'erreur soutenu au-dessus de votre référence normale.
• Traitez votre gestionnaire de webhook comme un chemin critique — il doit être l'un des services les plus fiables de votre infrastructure.
• Pour une maintenance planifiée, préférez stopper la réception au niveau du load balancer plutôt que de retourner 503. Les réponses non-2xx soutenues — y compris 503 — activent la réduction automatique du débit décrite ci-dessus ; lorsque votre endpoint récupère, le débit réduit retarde la livraison des événements mis en file d'attente pendant la panne. Ne retournez pas 200 pour des événements non traités.

Sémantique des statuts

Traitez l'ensemble des valeurs de state et lastEvent comme une configuration évolutive :

• Ne réagissez qu'aux états / événements que vous gérez explicitement.
• Journalisez les valeurs inconnues — n'émettez pas d'erreur à leur sujet.
• De nouveaux états peuvent être ajoutés sans changement de version majeure.