Fiabilité des webhooks dans les systèmes de paiement (Fiabilite Des Webhooks Dans Les Systemes DE Paiement)

Webhook n'est pas un message garanti

Le webhook que votre PSP vous envoie ne garantit pas que « cet événement se produira exactement une fois et dans le bon ordre ». Au contraire, il peut se décomposer de quatre manières différentes : le même événement peut arriver plus d'une fois, un événement peut ne pas arriver du tout, les événements peuvent arriver dans un ordre différent de celui dans lequel ils ont été envoyés et un événement peut arriver avec un retard de plusieurs minutes.```text PSP → Webhook ⚠ Duplicate: aynı olay iki kez ⚠ Missing: olay hiç gelmez ⚠ Out-of-order: capture bildirimi, authorize bildiriminden önce gelir ⚠ Delayed: olay dakikalar sonra ulaşır

## Concepts à la première mention```text
📦 Webhook
Bir dış sistemin (PSP), kendi tarafında gerçekleşen bir olayı bildirmek için sizin uç noktanıza yaptığı HTTP çağrısı.

📦 Signature Verification
Gelen webhook'un gerçekten PSP'den geldiğini, içeriğin değiştirilmediğini doğrulayan kriptografik kontrol.

📦 At-least-once Delivery
Bir olayın en az bir kez, bazen daha fazla kez teslim edileceğini garanti eden; ama sıra veya tekrar sayısı garantisi vermeyen teslimat modeli.

📦 ACK (Acknowledgement)
Webhook alıcısının, olayı aldığını PSP'ye bildiren hızlı HTTP cevabı (genellikle 200).

📦 Durable Write
İşlemin sonucu ne olursa olsun, olayın kalıcı depoya yazılmış olması; bellek içinde kalan bir kayıt değildir.
```Ces concepts répondent tous à une seule règle : votre gestionnaire de webhook doit d'abord enregistrer en toute sécurité l'événement entrant, quel qu'il soit, et ensuite seulement faire le gros du travail.

## Dupliquer : le même événement se produit deux fois

Si la PSP ne reçoit pas la réponse 200 de votre part à temps (problème de réseau, lenteur du serveur), elle renverra le même événement. Ce comportement n'est pas un bug, mais une conséquence naturelle de la garantie au moins une fois de la PSP. Le modèle identifiant d’événement + boîte de réception, que nous avons détaillé dans la cinquième section, constitue ici la première ligne de défense.```text
Webhook #1: evt_001 → işlenir
Webhook #2: evt_001 (tekrar) → inbox'ta zaten var, işlem atlanır, 200 döner
```## Manquant : l'événement n'arrive jamais

Parfois, le webhook n'arrive pas du tout : panne de réseau, erreur côté PSP ou votre point de terminaison temporairement injoignable. Un système qui s'appuie uniquement sur le webhook restera alors pour toujours dans l'état « ne sait pas ». C'est pourquoi le webhook devrait être le principal canal de notification, et non la seule source de vérité ; Un rapprochement périodique avec l'API de requête de statut de la PSP doit toujours servir de filet de sécurité secondaire.```text
Webhook (birincil, hızlı)
  + Periyodik durum sorgusu (ikincil, yavaş ama garantili)
  = webhook kaybolsa bile gerçek er ya da geç yakalanır
```## Hors service : les événements arrivent dans le désordre

La couche réseau ne garantit pas que les événements arrivent dans l'ordre dans lequel ils ont été envoyés. Par exemple, une notification « capture » ​​peut arriver avant une notification « autoriser » qui est censée arriver avant elle. Si votre gestionnaire met à jour la machine à états sans vérifier l'horodatage ou le numéro de version porté par l'événement, c'est là que les gardes que nous avons décrites dans la deuxième partie devraient entrer en jeu.```text
Gelen: payment.captured (t=2)
Gelen: payment.authorized (t=1, ama sonra ulaştı)
  → guard: t=1 olayı, zaten t=2'ye ulaşmış bir state'i geriye alamaz, sessizce reddedilir
```## Retardé : l'événement arrive avec du retard

Un webhook peut mettre quelques minutes à arriver en raison d'une file d'attente du côté PSP ou d'un retard de traitement de votre côté. Dans ce cas, votre gestionnaire doit faire la distinction entre « maintenant » et « au moment où l'événement se produit » ; Les erreurs de séquençage sont amplifiées si les décisions commerciales sont prises en fonction du moment où l'événement est traité plutôt que de son propre horodatage.

## Pourquoi vous ne devriez pas exécuter des tâches intensives de manière synchrone

Aucune tâche lourde ne doit être effectuée sur votre gestionnaire de webhook autre que la vérification de la signature, une vérification minimale et une écriture durable. Les étapes telles que la réduction des stocks, l'enregistrement financier et l'envoi de notifications doivent être transférées vers une tâche d'arrière-plan distincte.```text
Webhook Handler (hızlı, senkron)
  1. İmzayı doğrula
  2. Minimal şema kontrolü yap
  3. Olayı inbox'a yaz (durable)
  4. 200 OK döndür

Arka plan Job (yavaş, asenkron)
  5. İnbox'taki olayı oku
  6. Gerçek iş kararlarını uygula (stok, finans, bildirim)
```Cette distinction est essentielle pour deux raisons : premièrement, PSP impose généralement un court délai d'attente pour la réponse du webhook (quelques secondes) ; Si heavy duty dépasse ce délai, PSP considère la demande comme infructueuse et la renvoie, ce qui augmente le nombre de doublons. Deuxièmement, le fonctionnement synchrone de Heavy Duty rend votre gestionnaire de webhook dépendant des performances du système externe (si le service de stock est lent) ; cette dépendance peut également entraîner l'expiration du délai d'attente du webhook lui-même.

## Les confrontations les plus déroutantes de cet épisode```text
❌ Webhook, tek ve güvenilir gerçek kaynağıdır
✓ Webhook birincil bildirim kanalıdır; periyodik durum sorgusu ikincil güvenlik ağıdır

❌ 200 dönmek, işin tamamlandığı anlamına gelir
✓ 200, olayın güvenle alındığı anlamına gelir; işin tamamlanması ayrı bir asenkron adımdır

❌ Webhook'lar her zaman gönderildiği sırayla ulaşır
✓ Sıralama garanti edilmez; guard'lar olmadan state machine geriye kayabilir

❌ İmza doğrulaması opsiyoneldir, IP allowlist yeterlidir
✓ İmza doğrulaması, sahte veya değiştirilmiş webhook'lara karşı asıl savunmadır

Liste de contrôle pour votre gestionnaire de webhook

1. Votre gestionnaire de webhook effectue-t-il une vérification de signature à chaque demande, ou s'appuie-t-il uniquement sur la liste blanche d'adresses IP ?
2. Quelles tâches lourdes le gestionnaire exécute-t-il de manière synchrone avant d'écrire l'événement dans la boîte de réception ?
3. Si le webhook n'arrive jamais, combien d'heures/jours faut-il pour que votre système le remarque ? Avez-vous un travail de réconciliation?
4. Deux webhooks arrivant dans le désordre peuvent-ils mettre votre machine d'état dans un état invalide ? Avez-vous testé vos gardes ?
5. Quel est le délai d'expiration du webhook de la PSP et quelle quantité de celui-ci votre gestionnaire utilise-t-il ?

Si vous répondez « non, nous n'avons pas vérifié » à l'une de ces cinq questions, la crédibilité de votre webhook repose probablement sur une hypothèse non testée.

Choses à retenir de cette section

1. Les webhooks peuvent être en double, manquants, dans le désordre et en retard ; Votre gestionnaire doit prendre les quatre comme hypothèses.
2. La vérification des signatures est la principale ligne de défense contre les webhooks frauduleux ; La liste blanche IP ne suffit pas.
3. Le gestionnaire doit émettre un ACK rapide, confiant le gros du travail à un travail asynchrone ; Un travail lourd et synchrone augmente le risque d'expiration et de doublons.
4. Le Webhook est le canal principal mais pas la seule source de vérité ; Les sondages périodiques sur le statut devraient toujours constituer un filet de sécurité secondaire.

S'appuyer sur le webhook comme « l'avenir » n'est pas intentionnel ; Concevoir que « cela peut ne pas venir, cela peut revenir, cela peut devenir déréglé » est du design.