Skip to main content
En pocas palabras
Los webhooks envían notificaciones en tiempo real a tu servidor cuando ocurren eventos—depósitos, retiros, intercambios y más. En lugar de consultar la API, tu servidor recibe actualizaciones instantáneas cuando se completan las transacciones.

Requisitos Previos

Antes de configurar webhooks, asegúrate de tener:
1

Clave API

Obtén tu clave API desde el Panel de Blockradar. Navega a Developers para generar una.
2

Endpoint de Webhook

Crea un endpoint POST en tu servidor que pueda recibir cargas JSON y devolver una respuesta 200 OK.
3

URL HTTPS (Producción)

Para producción, tu URL de webhook debe usar HTTPS. Para pruebas locales, usa herramientas como ngrok o webhook.site.
4

Billetera Principal

Configura tu URL de webhook en tu billetera principal a través del panel.

Cómo Funciona

Cuando realizas una solicitud a un endpoint de API, esperas obtener una respuesta casi inmediata. Sin embargo, algunas solicitudes pueden tardar mucho tiempo en procesarse, lo que puede generar errores de tiempo de espera. Para evitar un error de tiempo de espera, se devuelve una respuesta pendiente. Dado que tus registros deben actualizarse con el estado final de la solicitud, necesitas:
  1. Realizar una solicitud de actualización (comúnmente conocido como polling) o,
  2. Escuchar eventos mediante el uso de una URL de webhook.
Consejo útil
Recomendamos que utilice webhooks para proporcionar valor a sus clientes en lugar de usar callbacks o polling. Con los callbacks, no tenemos control sobre lo que sucede del lado del cliente. Tampoco usted. Los callbacks pueden fallar si la conexión de red del dispositivo del cliente falla o es débil, o si el dispositivo se apaga después de una transacción.

Polling vs Webhooks

El polling requiere realizar una solicitud GET a intervalos regulares para obtener el estado final de una solicitud. Por ejemplo, cuando emite una dirección a un cliente para depósitos, sigue realizando solicitudes de transacciones vinculadas a la dirección hasta que encuentre una. Con webhooks, el servidor de recursos, Blockradar en este caso, envía actualizaciones a su servidor cuando cambia el estado de su solicitud. El cambio en el estado de una solicitud se conoce como evento. Normalmente escuchará estos eventos en un endpoint POST llamado su URL de webhook. La siguiente tabla destaca algunas diferencias entre polling y webhooks:

Crear una URL de webhook

Una URL de webhook es simplemente un endpoint POST al que un servidor de recursos envía actualizaciones. La URL necesita analizar una solicitud JSON y devolver un 200 OK:
Cuando su URL de webhook recibe un evento, necesita analizar y reconocer el evento. Reconocer un evento significa devolver un 200 OK en el encabezado HTTP. Sin un 200 OK en el encabezado de respuesta, seguiremos enviando eventos durante las próximas 2 horas y 35 minutos:
  • Intentaremos enviar webhooks 5 veces con un retraso creciente entre cada intento, comenzando con 5 minutos y aumentando exponencialmente hasta 80 minutos. La duración total de estos 5 intentos abarcará aproximadamente 2 horas y 35 minutos.
Evite tareas de larga duración
Si tiene tareas de larga duración en su función de webhook, debe reconocer el evento antes de ejecutar las tareas de larga duración. Las tareas de larga duración conducirán a un tiempo de espera de solicitud y una respuesta de error automática de su servidor. Sin una respuesta 200 OK, reintentamos como se describe en el párrafo anterior.

Probar Webhooks localmente

Durante el desarrollo, puede configurar su URL de webhook en su entorno de billetera maestra de PRUEBA a una dirección local, como http://localhost o 127.0.0.1. Para exponer su servidor local a Internet con fines de prueba, considere usar una herramienta como ngrok o webhook.site. Estas herramientas le permiten ver cómo se ve la carga útil del webhook y simular eventos de webhook localmente antes de implementar su aplicación en un entorno en vivo. Con estas herramientas, puede asegurarse de que su integración de webhook funcione correctamente y manejar cualquier problema en un entorno local controlado antes de pasar a producción.

Reenviar Webhook de Transacción

En caso de que por alguna razón no reciba el webhook de transacción y el tiempo de espera haya transcurrido, hemos proporcionado una API que puede usar para reenviar un webhook de transacción
¡Úselo con precaución!
Como esto puede llevar a procesar transacciones ya completadas, asegúrese de tener una validación adecuada al usar este endpoint.

Verificar el origen del evento

Dado que su URL de webhook está disponible públicamente, necesita verificar que los eventos provengan de Blockradar y no de un actor malicioso. Hay dos formas de asegurar que los eventos a su URL de webhook provengan de Blockradar:
  1. Validación de firma (recomendado)

Validación de firma

Los eventos enviados desde Blockradar llevan el encabezado x-blockradar-signature. El valor de este encabezado es una firma HMAC SHA512 de la carga útil del evento firmada usando su clave secreta. La verificación de la firma del encabezado debe realizarse antes de procesar el evento:

Lista de verificación para poner en producción

Ahora que ha creado exitosamente su URL de webhook, aquí hay algunas formas de asegurar que obtenga una experiencia agradable:
  • Agregue la URL de webhook en sus billeteras maestras en el panel de Blockradar
  • Asegúrese de que su URL de webhook esté disponible públicamente (las URLs de localhost no pueden recibir eventos)
  • Si usa .htaccess, recuerde agregar el / al final de la URL
  • Pruebe su webhook para asegurarse de que está recibiendo el cuerpo JSON y devolviendo una respuesta HTTP 200 OK
  • Si su función de webhook tiene tareas de larga duración, primero debe reconocer la recepción del webhook devolviendo un 200 OK antes de proceder con las tareas de larga duración
  • Si no obtenemos una respuesta HTTP 200 OK de sus webhooks, lo marcamos como un intento fallido
  • Intentaremos enviar webhooks 5 veces con un retraso creciente entre cada intento, comenzando con 5 minutos y aumentando exponencialmente hasta 80 minutos. La duración total de estos 5 intentos abarcará aproximadamente 2 horas y 35 minutos.

Tipos de eventos

Estos son los eventos que actualmente generamos. Agregaremos más a esta lista a medida que integremos más acciones en el futuro.

Ejemplos de Eventos

A continuación se muestran ejemplos de cargas útiles de webhook para algunos de los eventos más comunes:

Lista Completa de Eventos

Tipos y Estados de Transacciones

Tipos de Transacciones

Los siguientes tipos de transacciones se utilizan en las cargas útiles de webhook:

Estados de Transacciones

Los siguientes estados indican el estado actual de una transacción:
Estos tipos y estados de transacciones se utilizan en los campos type y status de las cargas útiles de webhook para ayudarlo a comprender qué tipo de transacción ocurrió y su estado actual.
¡Feliz codificación! ❤️