Fiabilidad del webhook en sistemas de pago (Fiabilidad Del Webhook EN Sistemas DE Pago)

Webhook no es un mensaje garantizado

El webhook que te envía tu PSP no garantiza que "este evento ocurrirá exactamente una vez y en el orden correcto". Más bien, puede descomponerse de cuatro maneras diferentes: el mismo evento puede llegar más de una vez, un evento puede no llegar en absoluto, los eventos pueden llegar en un orden diferente al orden en que fueron enviados y un evento puede llegar con un retraso de minutos.```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

## Conceptos en la primera mención```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.
```Todos estos conceptos cumplen una regla: su controlador de webhook primero debe registrar de forma segura cualquier evento entrante y solo entonces hacer el trabajo pesado.

## Duplicado: el mismo evento ocurre dos veces

Si la PSP no recibe su respuesta 200 a tiempo (problema de red, lentitud del servidor), reenviará el mismo evento. Este comportamiento no es un error, sino una consecuencia natural de la garantía de al menos una vez de la PSP. El patrón ID de evento + bandeja de entrada, que detallamos en la quinta sección, es la primera línea de defensa aquí.```text
Webhook #1: evt_001 → işlenir
Webhook #2: evt_001 (tekrar) → inbox'ta zaten var, işlem atlanır, 200 döner
```## Falta: el evento nunca llega

A veces, el webhook no llega en absoluto: una interrupción de la red, un error en el lado de PSP o un punto final temporalmente inaccesible. Un sistema que depende únicamente del webhook permanecerá en el estado "no sé" para siempre. Es por eso que el webhook debe ser el canal de notificación principal, no la única fuente de información; Una conciliación periódica con la API de consulta de estado del PSP siempre debería actuar como una red de seguridad secundaria.```text
Webhook (birincil, hızlı)
  + Periyodik durum sorgusu (ikincil, yavaş ama garantili)
  = webhook kaybolsa bile gerçek er ya da geç yakalanır
```## Fuera de orden: los eventos llegan desordenados

La capa de red no garantiza que los eventos lleguen en el orden en que fueron enviados. Por ejemplo, una notificación de "captura" puede llegar antes que una notificación de "autorización" que se espera llegue antes. Si su controlador actualiza la máquina de estado sin verificar la marca de tiempo o el número de versión que lleva el evento, aquí es donde las protecciones que describimos en la segunda parte deberían entrar en juego.```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
```## Retrasado: el evento llega retrasado

Un webhook puede tardar unos minutos en llegar debido a la cola del lado de PSP o a un retraso en el procesamiento de su parte. En este caso, su responsable debe distinguir entre “ahora mismo” y “el momento en que ocurre el evento”; Los errores de secuenciación aumentan si las decisiones comerciales se toman en función del momento en que se procesa el evento en lugar de su propia marca de tiempo.

## ¿Por qué no deberías ejecutar trabajos pesados sincrónicamente?

No se debe realizar ningún trabajo pesado en su controlador de webhook aparte de la verificación de firma, la verificación mínima y la escritura duradera. Pasos como la reducción de existencias, el registro financiero y el envío de notificaciones deben transferirse a un trabajo en segundo plano independiente.```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)
```Esta distinción es fundamental por dos razones: primero, PSP generalmente impone un tiempo de espera breve para la respuesta del webhook (unos pocos segundos); Si el servicio pesado excede este tiempo, PSP considera que la solicitud no tuvo éxito y la envía nuevamente, lo que aumenta la cantidad de duplicados. En segundo lugar, el funcionamiento sincrónico del servicio pesado hace que su controlador de webhook dependa del rendimiento del sistema externo (si el servicio estándar es lento); esta dependencia también puede hacer que el webhook expire.

## Los enfrentamientos más confusos de este episodio.```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

Lista de verificación para su controlador de webhook

1. ¿Su controlador de webhook realiza una verificación de firma en cada solicitud o simplemente depende de la lista de direcciones IP permitidas?
2. ¿Qué tareas pesadas ejecuta el controlador sincrónicamente antes de escribir el evento en la bandeja de entrada?
3. Si el webhook nunca llega, ¿cuántas horas/días le toma a su sistema darse cuenta? ¿Tienes un trabajo de reconciliación?
4. ¿Pueden dos webhooks que lleguen fuera de servicio poner su máquina de estado en un estado no válido? ¿Has probado a tus guardias?
5. ¿Cuál es el tiempo de espera del webhook de la PSP y cuánto utiliza su controlador?

Si responde “no, no verificamos” cualquiera de estas cinco preguntas, la credibilidad de su webhook probablemente se base en una suposición no probada.

Cosas para recordar de esta sección

1. Los webhooks pueden estar duplicados, faltantes, desordenados y retrasados; Su manejador debería tomar las cuatro como suposiciones.
2. La verificación de firmas es la principal línea de defensa contra los webhooks fraudulentos; La lista de IP permitidas no es suficiente.
3. El manejador debe emitir un ACK rápido, entregando el trabajo pesado a un trabajo asincrónico; El trabajo pesado sincrónico aumenta el riesgo de tiempos de espera y duplicados.
4. Webhook es el canal principal, pero no la única fuente de información; Las encuestas periódicas de estado siempre deben ser una red de seguridad secundaria.

Depender del webhook como “el futuro” no es una cuestión de diseño; Diseñar que “puede que no venga, puede que vuelva a venir, puede que se estropee” es diseño.