Webhooks de pagos cripto: eventos, seguridad y entrega fiable de pedidos

Los webhooks de pagos cripto son peticiones HTTP que la pasarela envía a tu servidor cada vez que una factura cambia de estado: transferencia detectada, confirmada en cadena, pago insuficiente, excesivo o caducado. Tu manejador verifica la firma, actualiza el pedido y lanza la entrega. Como los pagos cripto llegan de forma asíncrona, minutos después de que el cliente salga de tu página, la fuente de verdad es el webhook, no el navegador.

Esta guía se centra en la parte de webhooks de una integración: los eventos que recibirás, cómo verificarlos, cómo procesarlos con seguridad cuando el mismo evento llega dos veces y cómo probarlos y monitorizarlos. Para crear facturas, consulta nuestra guía de integración de la API de pagos cripto.

¿Por qué webhooks y no consultas o redirecciones?

• Una redirección no es prueba — que el cliente vuelva a tu página de «gracias» no dice nada sobre si llegó el dinero.
• Consultar es un derroche — preguntar a la API cada pocos segundos por cada factura abierta no escala y sigue llegando tarde.
• Los webhooks son push — la pasarela te avisa en cuanto algo cambia, con una firma verificable.

Los eventos que recibirás

Estos son los nombres de evento de mistKET. Otras pasarelas usan estados similares con nombres distintos; tradúcelos a tus estados de pedido en un único sitio.

Verificar la firma

Cualquiera puede enviar un POST a una URL pública, así que todo webhook debe autenticarse. mistKET firma cada entrega con HMAC-SHA256 y envía estas cabeceras:

• X-Mistket-Event — nombre del evento.
• X-Mistket-Timestamp — hora Unix incluida en la firma.
• X-Mistket-Signature — sha256= seguido del HMAC de {timestamp}.{raw body} con tu secreto de webhook.
• X-Mistket-Delivery — ID de entrega para los registros.

1. Lee el cuerpo en bruto — antes de parsear el JSON, porque recodificarlo cambia los bytes.
2. Recalcula el HMAC — sobre la marca de tiempo, un punto y el cuerpo en bruto, con tu secreto.
3. Compara en tiempo constante — con hash_equals, hmac.compare_digest o crypto.timingSafeEqual.
4. Rechaza marcas antiguas — por ejemplo de más de cinco minutos, para bloquear reenvíos maliciosos.
5. Solo entonces parsea y actúa — y responde 2xx rápidamente.

La construcción sigue el patrón estándar HMAC; guarda el secreto en el servidor y rótalo si se filtra.

Elegir y proteger la URL de callback

Usa una ruta HTTPS dedicada, como /webhooks/mistket, separada de tus páginas normales, y pásala como callback al crear cada factura. Exclúyela de la protección CSRF, la caché y las redirecciones: una redirección 301 o una respuesta cacheada es una causa habitual de webhooks que fallan en silencio. No exijas cookie de sesión; la pasarela no es un usuario logueado y la autenticación es la firma HMAC. Por último, registra cada entrega con su evento, ID de pedido y código de respuesta para poder contestar «¿llegó el webhook?» en segundos.

Idempotencia: el mismo evento puede llegar dos veces

Si tu endpoint tarda demasiado o devuelve un error, la pasarela reintenta con espera progresiva durante horas. Un fallo de red también puede entregarte un evento que ya procesaste. Por eso tu manejador debe ser idempotente:

• Usa el ID de pedido como clave — busca el pedido al que hace referencia la factura.
• Comprueba el estado actual — si ya está entregado, confirma la recepción y no hagas nada más.
• Usa una transacción o un bloqueo — para que dos entregas paralelas no envíen ambas el producto.
• Guarda el ID de entrega — útil para depurar duplicados.

Diseñar los estados del pedido según los eventos

Una máquina de estados sencilla evita la mayoría de errores: pendiente → confirmando (con paid) → pagado (con confirmed) → entregado, con ramas para insuficiente y caducado. Permite solo transiciones hacia delante. Un invoice.paid que llega después de invoice.confirmed nunca debe hacer retroceder un pedido. Los pagos tardíos a facturas caducadas deben crear un registro para revisión en lugar de reabrir el pedido en silencio.

Gestionar los casos incómodos

• Pago insuficiente — indica al cliente el importe exacto que falta y que puede enviarlo a la misma página de pago; los pagos parciales se suman.
• Pago excesivo — entrega y luego decide entre saldo a favor o una transferencia de reembolso según tu política.
• Caducado — libera el stock y ofrece una nueva factura si el cliente aún quiere comprar.
• Red equivocada — se resuelve desde soporte, no desde el código; muestra la red claramente en el checkout para evitarlo.

Pruebas y monitorización

1. Expón un endpoint de pruebas — por HTTPS, registrando cabeceras y cuerpos en bruto.
2. Provoca cada evento — paid, confirmed, underpaid, overpaid y expired, con pequeños pagos reales.
3. Reenvía una entrega — confirma que tu manejador ignora el duplicado.
4. Rompe la firma — cambia un byte y comprueba que se rechaza la petición.
5. Revisa los registros de entrega — el panel muestra cada intento, su código de respuesta y el hash de la transacción.
6. Alerta ante fallos — un pico de respuestas no 2xx significa pedidos sin entregar.

Los bots y comunidades de pago siguen el mismo patrón; mira cómo encaja en un chat en aceptar pagos cripto en un bot de Telegram.

Webhooks con mistKET

mistKET envía webhooks firmados con HMAC para cada estado de factura, reintenta las entregas fallidas con espera progresiva y muestra en el panel los registros de entrega, los importes esperados y recibidos y los hashes de transacción. Las peticiones a la API se firman igual, así que una sola función auxiliar cubre ambos sentidos.

Revisa ejemplos de peticiones y webhooks en la sección para desarrolladores, consulta los precios y gestiona tus claves desde el acceso de comercio. Para obtener acceso, solicítalo en Telegram en @mistnetwork.