Webhooks de pagos cripto: cómo funcionan y cómo construirlos

Un webhook de pago cripto es una petición HTTP que un servicio de blockchain envía a su servidor cuando ocurre algo en la cadena, como la llegada de un depósito a la dirección de un cliente. En lugar de preguntar a la red cada pocos segundos si ha llegado un pago, usted da al proveedor una URL y él le llama.

Para ejecutar esto en producción necesita cuatro cosas: un endpoint público, verificación de firmas, un tratamiento idempotente de los eventos duplicados y una alternativa para las entregas perdidas. Esta guía cubre cada una.

TL;DR

• Un webhook envía un evento a su servidor cuando se produce un pago o un evento de wallet. Así evita el sondeo constante y la carga que este genera en su sistema.
• Verifique la firma de cada petición antes de confiar en cualquier campo. Con Chaingateway, la firma cubre solo el ID de la transacción, así que compruebe usted mismo el importe y el destinatario.
• Responda con un 2xx rápidamente y haga el trabajo real en un proceso en segundo plano.
• Considere que cada evento puede repetirse: guarde los ID de evento y haga idempotentes las actualizaciones de pedidos.
• Mantenga un trabajo lento de conciliación para los pagos pendientes. Chaingateway no reintenta por sí mismo las notificaciones fallidas, así que una entrega perdida dejaría un pedido bloqueado.

¿Qué son los webhooks de pagos cripto?

Un webhook es una llamada de retorno. Registre una URL e indique al proveedor qué eventos le interesan. Cuando uno de ellos ocurre, el proveedor envía una petición POST con un cuerpo JSON que lo describe. En los pagos cripto, esos eventos suelen ser una transferencia entrante a una dirección vigilada, una transferencia saliente o una transferencia de token en un contrato.

La alternativa es el sondeo. Su servidor llama a una API con un temporizador y compara el resultado con lo que vio la última vez. El sondeo es sencillo de escribir y derrochador de ejecutar. Cada petición que no devuelve nada nuevo le cuesta límite de peticiones, cómputo y latencia, y el retraso entre un pago y su reacción es igual a su intervalo. Con varias cadenas y miles de direcciones de clientes, el número de llamadas se multiplica rápidamente.

Los webhooks invierten el sentido. El proveedor vigila la cadena, compara las transacciones con las direcciones que usted ha suscrito y le notifica una sola vez. El tiempo de reacción baja a segundos, y su propia infraestructura permanece inactiva hasta que hay algo que hacer. Hemos explicado el argumento completo para los depósitos en cómo procesar depósitos automáticamente con webhooks.

Webhooks frente a sondeo de un vistazo

La última fila es la respuesta práctica. Los webhooks deben ser la señal principal, y el sondeo, una red de seguridad lenta que comprueba solo los pagos todavía pendientes. Haga la comprobación solo para las facturas aún pendientes, así una entrega perdida se detecta en minutos y el número de peticiones se mantiene bajo.

¿Cómo detecta un webhook un pago cripto?

La parte del proveedor es la que no se ve, pero entenderla explica la mayoría de los comportamientos que encontrará en las pruebas.

1. Suscripción. Cree una wallet o registre una dirección, y después registre un webhook para ella mediante la API del proveedor. La suscripción contiene su URL de callback y filtros como remitente, receptor, dirección de contrato y tipo de transacción.
2. Vigilancia. El proveedor mantiene nodos para cada cadena soportada y lee cada bloque nuevo. Cada transacción se compara con las suscripciones y, en el caso de tokens, con los logs de transferencia del contrato.
3. Decodificación. Los datos brutos de la cadena no son amigables. Una transferencia de token en Ethereum es una entrada de log codificada, y Bitcoin tiene entradas y salidas en lugar de un remitente y un destinatario. El proveedor lo convierte en una carga legible.
4. Entrega. El proveedor envía la carga a su URL. Si su servidor no responde con un código de éxito, lo que ocurre después depende del proveedor. Algunos reintentan según un calendario. Chaingateway no reintenta por sí mismo: lista las notificaciones fallidas, y usted pide que cada una se vuelva a enviar.

Una notificación de Chaingateway contiene los campos id, webhook_id, from, to, blocknumber, datetime, type, contractaddress, tokenid, txid y amount. Se usan los mismos nombres de campo en Ethereum, BNB Smart Chain, Polygon, Arbitrum y Tron. Los webhooks de Bitcoin filtran solo por remitente y receptor. Solana no tiene webhooks. Se admiten estándares de token como ERC-20, BEP-20 y TRC-20, lo que importa porque la mayoría de los pagos reales son transferencias de stablecoins y no de la moneda nativa.

Eventos que conviene suscribir

Empiece en un ámbito reducido. En Chaingateway, un webhook se define por filtros, así que cada tipo de evento corresponde a una combinación de filtros:

• Una transferencia entrante a una dirección de depósito de cliente usa to. Es el evento central para abonar una cuenta o marcar una factura como pagada.
• Una transferencia saliente usa from, por ejemplo para ver cuándo llega a la cadena un pago de salida o un barrido.
• Una transferencia de token usa type (como ERC20 o TRC20) con una contractaddress.
• Una transferencia de NFT usa el campo token_id con un tipo ERC721 o TRC721.
• El campo opcional reference, de hasta 255 caracteres, le permite asociar un webhook con un pedido o un cliente de su propio sistema.

Una notificación anuncia que se vio una transacción que coincide con el filtro. Si la trata como definitiva es decisión de su propia política, como explica la sección sobre la profundidad de confirmación.

Nuestra entrada sobre webhooks de Polygon sin sondeo muestra cómo se ve esto en una sola cadena.

¿Cómo se configura y procesa un endpoint de webhook?

El endpoint es una ruta HTTPS ordinaria de su servidor. La diferencia entre una demostración y un manejador de producción está en unos pocos hábitos.

Requisitos del endpoint

La URL debe ser accesible desde Internet público mediante HTTPS. Las direcciones localhost y las redes privadas no pueden recibir llamadas, así que durante el desarrollo necesitará un túnel que exponga su puerto local. Reserve la ruta para webhooks, acepte solo POST, y no la ponga detrás de pantallas de inicio de sesión ni de middleware CSRF que rechazaría una petición procedente de una máquina.

El manejador debe responder rápido. La recomendación habitual, por ejemplo en la documentación de webhooks de Stripe, es devolver pronto un código de éxito, antes de cualquier lógica compleja que pueda agotar el tiempo de espera. Éxito significa un estado 2xx según RFC 9110. La misma regla se aplica a los eventos cripto. Si actualiza una base de datos, envíe un correo y llame a un sistema contable antes de responder, un servicio posterior lento puede hacer que el proveedor considere fallida la entrega.

Un patrón fiable tiene este aspecto:

1. Leer el cuerpo de la petición.
2. Verificar la firma.
3. Escribir el evento en una cola o en una tabla de eventos con su ID.
4. Devolver 200.
5. Dejar que un worker procese el evento en cola.

¿Cómo se verifican las firmas de los webhooks?

Cualquiera que encuentre su URL puede enviarle JSON. Si su manejador abona una cuenta porque una petición dice que llegó un depósito, una petición falsificada es un robo. La verificación de firma cierra esa puerta.

El esquema habitual es HMAC, definido en la RFC 2104. El proveedor calcula un hash con clave usando un secreto que solo conocen usted y él, y envía el resultado en una cabecera. Usted recalcula el hash y lo compara. Tres detalles hacen tropezar a la gente:

• Sepa qué se firma. Muchos proveedores firman el cuerpo completo de la petición, lo que significa que debe verificar con los bytes originales, no con JSON serializado de nuevo. Chaingateway firma solo el ID de la transacción.
• Compare en tiempo constante. Use la función de comparación segura de su lenguaje en lugar de una simple igualdad.
• Compruebe una marca de tiempo cuando el esquema la proporciona. Rechazar las marcas antiguas limita la reproducción de una petición capturada. El esquema de Chaingateway no tiene marca de tiempo, así que deduplique por ID de transacción.

Chaingateway envía la firma en una cabecera X-Signature una vez que ha definido un secreto personal en su perfil. El valor es el HMAC-SHA256 codificado en Base64 del campo txid, con ese secreto como clave. La guía de verificación de firmas incluye un manejador funcional en Node.js, y la documentación tiene versiones en Python, Java y PHP. Como solo se firma el txid, una firma válida no demuestra que amount o to no hayan cambiado. Compárelos con su factura, o con la cadena, antes de abonar nada.

Guarde el secreto en una variable de entorno o en un gestor de secretos, nunca en el repositorio, y regénérelo si alguna vez aparece en un log. Un secreto regenerado surte efecto de inmediato.

¿Cómo se gestionan los reintentos, los duplicados y las confirmaciones lentas?

Las redes fallan y los despliegues reinician servidores. Su manejador acabará viendo dos veces el mismo evento, por ejemplo tras un reenvío, y a veces eventos fuera de orden. Diséñelo para eso desde el principio.

Haga el procesamiento idempotente

Cada evento lleva algo que lo identifica. En una notificación de Chaingateway, es el txid junto con el webhook_id. Guarde ese identificador con una restricción de unicidad antes de actuar. Si la inserción falla porque la clave ya existe, ya vio el evento y puede devolver 200 sin hacer nada más.

Después, haga seguro repetir la propia acción de negocio. «Marcar la factura 1042 como pagada con la transacción X» es idempotente. «Sumar 50 al saldo» no lo es. Prefiera la primera forma, o vincule el cambio de saldo al registro único del evento dentro de una sola transacción de base de datos.

Respete la profundidad de confirmación

Que una transacción aparezca en un bloque no equivale a un pago contra el que pueda enviar mercancía. Las cadenas difieren en la rapidez con la que un bloque se vuelve improbable de revertir, y el umbral correcto depende del importe y del activo. Defina una política por cadena y por tamaño de pedido, y guarde el estado de cada pago: detectado, confirmando, confirmado, fallido. El webhook que anuncia la detección debe pasar un pedido a «pago visto», no a «cumplido».

Pagos insuficientes, excesivos y tokens equivocados

Los clientes envían el importe equivocado con más frecuencia de lo que cree cualquiera. Su manejador debe comparar el importe y el activo recibidos con la factura y bifurcar: coincidencia exacta, pago corto, pago excesivo o un token inesperado. Decida de antemano si abona automáticamente la diferencia, la retiene para revisión o reembolsa. Un payload decodificado con el activo y el importe como campos separados convierte esta comparación en unas pocas líneas de código, en lugar de un ejercicio de análisis.

Mantenga una red de seguridad

Una entrega puede fallar, y Chaingateway no la reintenta. Las notificaciones fallidas aparecen en GET /api/v2/<chain>/webhooks/notifications/failed, y cada una se reenvía con POST /api/v2/<chain>/webhooks/notifications/{id}/retry. Ejecute un trabajo programado, cada pocos minutos, que revise esa lista y mire las facturas que siguen pendientes más allá de un tiempo razonable. Cuando encuentre un pago que su webhook nunca reportó, lo pasa por el mismo camino de procesamiento. Un único camino de código para ambas fuentes significa un único conjunto de errores.

¿Cómo se prueba y se monitoriza un endpoint de webhook?

Construya la confianza por capas:

1. Prueba local. Escriba un script pequeño que firme un payload de ejemplo con su secreto de prueba y lo envíe a su endpoint. Confirme que una firma válida pasa y que un txid modificado falla.
2. Ejecución en testnet. Cree una wallet en una red de pruebas con la cabecera X-Network: testnet, registre un webhook y envíe una transferencia pequeña desde un faucet. Verá la secuencia real de eventos, incluido el retraso antes de la notificación, algo que ningún payload de ejemplo enseña.
3. Simulacro de duplicados. Envíe el mismo evento válido cinco veces. Su factura debe cambiar una sola vez, y sus logs deben mostrar cuatro duplicados omitidos.
4. Simulacro de fallo. Haga que su manejador devuelva 500 a propósito. Después localice la notificación en la lista de fallidas, restaure el manejador y reenvíela. Debe procesarse una sola vez.

Una vez en producción, registre el ID de cada evento entrante, el resultado de la verificación, el resultado del procesamiento y el tiempo empleado. Configure alertas para tres cosas: fallos de firma (un secreto mal configurado o un atacante), una cola que crece (workers que se quedan atrás) y facturas pendientes mucho más tiempo de lo normal (problemas silenciosos de entrega).

Problemas habituales y sus causas más probables:

¿Cómo empezar a recibir eventos de pago con Chaingateway?

Cree un webhook con una sola petición a POST /api/v2/<chain>/webhooks. El ejemplo registra un vigilante de depósitos TRC20 con una referencia a su pedido:

curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "TWrTTVizHkF3LxTiWE9vCnhWC7CBpNXe22",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "type": "TRC20",
    "url": "https://shop.example.com/hooks/crypto",
    "reference": "order-10442"
  }'

Los webhooks de Chaingateway funcionan junto con la API Blockchain, de modo que el evento que le avisa de que llegó un depósito y la llamada que lo envía después viven bajo una misma cuenta.

Los planes se publican en la página de precios: Plus cuesta 49 € al mes, Pro 99 €, Premium 249 € y Enterprise 499 €, o 490 €, 990 €, 2.490 € y 4.990 € al año con facturación anual. La prueba gratuita de 7 días no requiere tarjeta ni KYC, así que puede conectar su endpoint y hacer primero los simulacros de arriba.

Fuentes

• Webhooks, documentación de Stripe
• HMAC: Keyed-Hashing for Message Authentication, RFC 2104
• Successful 2xx status codes, HTTP Semantics, RFC 9110

Recomendado

• Cómo procesar depósitos automáticamente con webhooks
• Webhooks frente a WebSockets para desarrolladores: patrón de ingesta, cola y distribución
• Webhooks de Polygon: eventos on-chain en tiempo real sin sondeo
• Alertas cripto en tiempo real: aplicaciones de precios frente a alertas por webhook