Garantías de entrega de webhooks explicadas

Rutas abstractas representan la entrega de un webhook y su acuse de recibo

Las garantías de entrega de webhooks describen con qué frecuencia y en qué orden entrega un proveedor los eventos a su endpoint. La mayoría de los proveedores prometen, como mucho, entrega al menos una vez. Su endpoint recibe la mayoría de los eventos, a veces dos veces, tarde o desordenados. Las integraciones fiables ponen las salvaguardas en el lado receptor.

Esta guía explica cada garantía en lenguaje sencillo, muestra lo que prometen en realidad las documentaciones de proveedores reales y termina con una lista de comprobación para cualquier integración de webhooks, incluidos los eventos de pagos cripto.

TL;DR

Al menos una vez es el techo realista. Los proveedores reintentan hasta que usted devuelve una respuesta 2xx, así que los duplicados son normales y tiene que tratarlos.
El orden no está garantizado. Un evento anterior que agotó el tiempo de espera puede llegar después de uno posterior, así que ordene por la marca de tiempo o el campo de secuencia del propio evento.
Acuse recibo primero, procese después. Verifique la firma, guarde el evento de forma duradera, devuelva 2xx y haga el trabajo pesado de forma asíncrona.
Deduplique por el ID del evento. Regístrelo con un índice único antes de cualquier efecto secundario, como acreditar un saldo.
Trate los webhooks como notificaciones, no como un libro mayor. Concilie los registros críticos con la API de forma periódica para detectar lo que los reintentos pasaron por alto.
Chaingateway no reintenta automáticamente las notificaciones fallidas. Las lista y las reenvía cuando usted lo pide.

¿Qué significan las tres garantías de entrega?

La semántica de entrega viene de los sistemas distribuidos y se aplica bien a los webhooks.

Garantía	Qué hace el emisor	Qué puede salir mal	Qué construye usted
A lo sumo una vez	Envía el evento una vez y nunca reintenta	El evento se pierde si su endpoint está caído	Conciliación con la API
Al menos una vez	Reintenta hasta que usted acusa recibo o se agotan los reintentos	Duplicados, llegadas tardías, reordenación	Gestor idempotente, deduplicación
Exactamente una vez	Entregaría una sola vez, sin pérdidas ni duplicados	No se puede lograr a través de una frontera de red poco fiable	Al menos una vez más deduplicación

Con a lo sumo una vez, un intento fallido significa un evento perdido. Es sencillo para el emisor e inseguro para cualquier cosa que implique dinero.

Con al menos una vez, el emisor sigue intentándolo hasta ver una respuesta de éxito o agotar su presupuesto de reintentos. La pérdida se vuelve rara, pero hay un problema. Suponga que su gestor acredita una cuenta y falla antes de devolver 200. El emisor nunca vio el acuse de recibo, así que envía el evento de nuevo. Desde el lado del emisor, eso es un comportamiento correcto. Desde el suyo, es un doble abono salvo que lo evite.

Exactamente una vez es lo que todos quieren y nadie puede prometer sobre HTTP. El emisor no puede saber si su servidor procesó la solicitud cuando se corta la conexión. El sustituto práctico es la entrega al menos una vez combinada con un receptor que ignora las repeticiones. Esa combinación da efectos de exactamente una vez, que es lo que de verdad importa.

¿Qué prometen realmente los proveedores?

Lea la sección de entrega de la documentación de cualquier proveedor de webhooks serio y aparece el mismo patrón.

Adobe I/O Events indica que cada evento se entrega al menos una vez por registro, que puede haber duplicados y que no se garantiza el orden de los eventos. Column, una API bancaria estadounidense, afirma que no se garantiza que los eventos de webhook lleguen en el orden de creación. Un evento anterior que agotó el tiempo de espera puede llegar después de uno posterior, porque cada reintento se reprograma de forma independiente.

Ese último detalle explica la mayoría de los errores de orden. El evento A falla una vez y se programa un reintento dentro de un minuto. El evento B, creado después, tiene éxito de inmediato. Su sistema ve B y luego A. Nada falla por parte del proveedor. La garantía simplemente nunca cubrió el orden.

Orden: use el reloj del evento, no el de la entrega

La guía de webhooks de Wise recomienda reconstruir la cronología a partir de las marcas de tiempo de los eventos o, cuando existan, de ID de secuencia monótonamente crecientes, en lugar de a partir del momento en que se despachó la notificación. Su documentación señala que la hora de envío puede diferir de la hora en que ocurrió el evento, sobre todo durante los reintentos.

En la práctica:

Guarde la marca de tiempo de negocio del evento o su número de secuencia junto con la carga.
Cuando llegue un evento, compárelo con el último estado que tiene de ese objeto.
Si el evento entrante es más antiguo que lo que ya aplicó, regístrelo, pero no deje que sobrescriba el estado más reciente.

Para un estado de pago que pasa de pendiente a confirmado, esto evita que un evento «pendiente» tardío devuelva un pago confirmado a su estado anterior.

¿Cómo funcionan los reintentos de webhooks y cuándo terminan?

Las políticas de reintento varían, pero la forma es coherente: retroceso exponencial, un tope y una parada definitiva. Chaingateway es una excepción, porque no reintenta automáticamente.

Proveedor	Comportamiento de reintento (según su documentación)
Column	Hasta 25 reintentos en tres días, retroceso exponencial, primer reintento un minuto después de la entrega fallida
Probo	Hasta 12 intentos, retroceso exponencial con jitter completo desde una base de 30 segundos, con tope de cuatro horas
Stripe	Retroceso exponencial en modo live durante hasta tres días
Chaingateway	Sin reintento automático. Las notificaciones fallidas se listan en `GET /api/v2/{chain}/webhooks/notifications/failed` y se reenvían con `POST /api/v2/{chain}/webhooks/notifications/{id}/retry`

Fuentes: documentación de Column, Probo y Stripe, consultada el 5 de noviembre de 2026, y la especificación OpenAPI de Chaingateway.

La documentación de Probo añade detalles útiles. Reintenta los errores de red, los tiempos de espera agotados y las respuestas 408, 425, 429 o 5xx, y respeta una cabecera Retry-After hasta su tope. Cuando se agotan los intentos, la entrega se marca como fallida y no se vuelve a poner en cola.

De aquí se desprenden dos lecciones. Primera, los códigos de error de su endpoint son señales: un 5xx le dice al emisor que lo intente de nuevo, así que devuélvalo solo cuando de verdad quiera un reintento. Segunda, la ventana de reintentos es finita. Si su servicio está caído más tiempo que la ventana, esos eventos desaparecen de la cola de reintentos y necesita otra forma de recuperarlos.

¿Por qué debo acusar recibo rápido y procesar después?

Una entrega cuenta como exitosa cuando usted devuelve un estado 2xx. Column considera entregado un evento cuando recibe un 2xx en 10 segundos y recomienda devolverlo justo después de recibirlo, antes de un procesamiento sustancial. La documentación de NestJS trata el 2xx como éxito y todo lo demás, incluidas las redirecciones, los tiempos de espera agotados y las conexiones rechazadas, como fallo.

Así que el trabajo del gestor es acotado:

Leer el cuerpo en bruto.
Verificar la firma.
Comprobar el tipo y el ID del evento.
Escribir el evento en un almacenamiento duradero (una fila de base de datos o un mensaje de cola).
Devolver 200, 202 o 204.

Todo lo demás, como actualizar saldos, enviar correos o llamar a otros servicios, se ejecuta desde un worker que lee de ese almacenamiento. Si hace el trabajo lento en línea, una consulta lenta a la base de datos se convierte en un tiempo de espera agotado, este en un reintento y el reintento en un duplicado. El enfoque de ingesta, cola y distribución se trata en nuestro propio artículo sobre webhooks frente a WebSockets.

¿Cómo hago inofensivos los duplicados?

Como la entrega al menos una vez implica repeticiones, su gestor debe ser idempotente. El método estándar es simple.

La recomendación de Probo es verificar la firma, confirmar la organización y el tipo de evento esperados y luego registrar de forma atómica el ID del evento con un índice único antes de cualquier efecto secundario. Una solicitud posterior con un ID que ya registró se ignora. Stripe da el mismo consejo: registrar los ID de evento procesados y omitir cualquier evento ya tratado. Muchos proveedores lo facilitan incluyendo un ID único en cada carga. Adobe, por ejemplo, pone un UUID en la carga y lo repite en una cabecera x-adobe-event-id.

Un patrón mínimo:

Inserte el ID del evento en una tabla con una restricción de unicidad.
Si la inserción falla porque el ID ya existe, devuelva 200 y deténgase.
Si tiene éxito, ponga el trabajo en cola.

El orden importa. Registre primero, actúe después. Si actúa primero y falla antes de registrar, el reintento repite la acción. Si registra primero y falla antes de actuar, su worker debe recoger los registros sin terminar al reiniciarse, para que el evento no se descarte en silencio.

Para movimientos de dinero, añada una segunda capa: haga idempotente también la operación de negocio. Use como clave de un abono el hash de la transacción y el índice del log, o el ID del pago, de modo que ni siquiera un error en la tabla de eventos pueda acreditar dos veces el mismo pago.

¿Cómo verifico cada solicitud?

Un endpoint de webhook es una URL pública que activa acciones en su sistema. Cualquiera puede enviarle un POST salvo que compruebe quién envió la solicitud.

Stripe exige verificar con el cuerpo en bruto de la solicitud, la cabecera de firma y el secreto de su endpoint. El consejo de Probo es usar el cuerpo intacto y verificar la firma antes de analizar el JSON, y luego aplicar una comprobación de frescura de la marca de tiempo. Analizar y volver a serializar el cuerpo antes de verificar es una causa clásica de firmas que nunca coinciden.

Una rutina de verificación sólida para proveedores que firman el cuerpo:

Calcule el HMAC sobre los bytes exactos recibidos, con su secreto.
Compárelo con el valor de la cabecera mediante una comparación en tiempo constante.
Rechace las solicitudes cuya marca de tiempo quede fuera de una ventana de tolerancia corta, para limitar las capturas reenviadas.
Solo entonces analice el JSON y mire el tipo de evento.

Chaingateway funciona de otra manera. Calcula un HMAC-SHA256 en Base64 sobre el txid de la carga y lo envía en la cabecera X-Signature. La documentación de firmas muestra la comprobación, y nuestro artículo sobre la función de seguridad de webhooks explica la configuración.

¿Cómo recupero los eventos que los reintentos no entregaron?

Incluso un receptor perfecto pierde eventos en algunos escenarios: una caída más larga que la ventana de reintentos, un firewall mal configurado, un despliegue que devolvió 500 durante horas. Las opciones de recuperación varían según el proveedor. Probo no tiene reproducción manual y no vuelve a poner en cola las entregas fallidas; espera que usted configure alertas para los fallos y concilie con su API. Stripe señala que los operadores pueden procesar manualmente un atraso para acelerar la recuperación. Column dice que los eventos que faltan o los adicionales pueden obtenerse mediante sus API de eventos cuando los fallos exigen conciliar.

Técnico conectando cables en un rack de servidores, como imagen de las caídas de infraestructura que pueden provocar entregas de webhooks perdidas

El principio de diseño común, expuesto con claridad en la documentación para desarrolladores de ThriveDesk, es tratar los webhooks como notificaciones y no como el único libro mayor de eventos. Guarde las cargas de forma duradera, procéselas de forma asíncrona y concilie periódicamente los registros críticos con la API REST.

Un trabajo de conciliación puede ser pequeño:

Según un calendario, liste los objetos que importan (pagos, carteras, pedidos) desde la API del proveedor para la última ventana.
Compare su estado con sus propios registros.
Aplique las diferencias por la misma ruta de código idempotente que usa su gestor de webhooks.
Genere una alerta si el trabajo encuentra huecos con frecuencia, porque eso apunta a un problema del endpoint.

Como un evento posterior suele llevar el estado actual completo de un objeto, es posible que el siguiente sobrescriba de todos modos un evento intermedio perdido. La conciliación cubre los casos en que no hay un siguiente.

¿Cómo se aplican estas garantías a los eventos de pagos cripto?

Los pagos on-chain suben lo que está en juego, porque un evento perdido o duplicado es un abono perdido o duplicado. Algunos hábitos ayudan con cualquier proveedor:

Use identificadores de cadena como clave de los abonos. Use el hash de la transacción más el índice de la transferencia dentro de ella, no solo el ID de entrega del webhook.
Modele el estado como una progresión. Pendiente, confirmado y final son estados con un orden. No deje nunca que un estado más antiguo sobrescriba uno más reciente.
Contraste con sus propios datos. Busque en su base de datos la dirección receptora o la referencia antes de acreditar; ignore los eventos de direcciones que no son suyas.
Concilie los saldos. Una comparación periódica de su libro mayor con los saldos de las carteras que da la API detecta todo lo que el flujo de eventos haya omitido.

Nuestro recorrido por procesar depósitos automáticamente con webhooks sitúa estos pasos en un flujo de pago, y la guía de webhooks de Polygon muestra la alternativa basada en eventos al sondeo en una cadena concreta.

Nuestra perspectiva

Creamos webhooks para desarrolladores que mueven dinero, así que pensamos en las garantías de entrega todos los días: nuestra opinión es que ningún proveedor honesto puede prometer entrega exactamente una vez, y la respuesta correcta es un contrato limpio: los eventos son notificaciones, las solicitudes firmadas prueban de dónde vienen y la API siempre está ahí como fuente de verdad.

Por eso combinamos notificaciones de eventos en tiempo real con una API REST unificada para todas las cadenas. Los webhooks le dicen que algo ocurrió; la API le permite confirmarlo, obtener datos de transacción decodificados y conciliar cuando lo necesite. Nuestros webhooks van firmados con HMAC para que su receptor pueda verificarlos, y la carga incluye el remitente, el destinatario, el contrato del token y el importe decodificados, de modo que su gestor dedica su tiempo a la lógica de negocio en lugar de analizar logs en bruto.

También creemos que los equipos no deberían tener que ejecutar sus propios nodos ni manejar endpoints específicos de cada cadena para llegar ahí: una integración, un esquema de firma y una forma de consultar el estado en Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain y Arbitrum significa menos lugares donde pueda esconderse un caso límite de entrega.

Bitblade

Cree sobre webhooks firmados y multicadena

Si añade pagos cripto a una aplicación, los Webhooks de Chaingateway entregan notificaciones de eventos de blockchain con firmas HMAC, respaldados por una única API de Blockchain para carteras, transferencias, transacciones decodificadas y precios del gas. Los planes de la página de precios empiezan en 49 € al mes para Plus, con Pro a 99 €, Premium a 249 € y Enterprise a 499 € al mes, o desde 490 € con facturación anual.

Captura de la página de inicio de Chaingateway con el titular sobre una API de blockchain unificada para pagos cripto y webhooks y un botón para iniciar una prueba gratuita de 7 días

Combine el flujo de webhooks con el patrón de conciliación descrito arriba y tendrá notificaciones rápidas con una red de seguridad.

Preguntas frecuentes

¿Es posible la entrega de webhooks exactamente una vez?

No a través de una conexión HTTP poco fiable. El emisor no puede saber si su servidor procesó una solicitud cuando se pierde la respuesta. El enfoque práctico es la entrega al menos una vez más la deduplicación por el ID del evento, que produce efectos de exactamente una vez en su sistema.

¿Qué código de estado debe devolver mi endpoint de webhook?

Devuelva un código 2xx, como 200, 202 o 204, en cuanto haya verificado y almacenado el evento de forma duradera. Proveedores como Column solo cuentan una entrega como exitosa con un 2xx en 10 segundos. Devuelva 5xx solo cuando quiera que el emisor reintente.

¿Por qué llegan desordenados los eventos de webhook?

Los reintentos se programan de forma independiente para cada evento. Si el evento A agota el tiempo de espera y el evento B tiene éxito, B llega primero y A aparece después de su reintento. Proveedores como Adobe y Column dicen claramente que el orden no está garantizado, así que ordene por la marca de tiempo o el campo de secuencia del evento.

¿Qué ocurre si mi servidor está caído cuando se envía un webhook?

La mayoría de los proveedores reintentan con retroceso exponencial durante una ventana limitada, de hasta unos tres días en la documentación que revisamos. Después, es posible que el evento no se vuelva a poner en cola. Chaingateway no reintenta automáticamente. Lista las notificaciones fallidas y las reenvía cuando usted lo pide. En ambos casos, ejecute una conciliación periódica con la API del proveedor para recuperar lo que se haya perdido.

¿Necesito verificar las firmas de los webhooks?

Sí. Su endpoint es accesible públicamente, y una comprobación de firma con el cuerpo en bruto y su secreto es la forma de saber que una solicitud vino del proveedor. Añada una tolerancia de marca de tiempo para reducir el riesgo de reenvío.