Saltearse al contenido

Webhooks de pago blockchain: cómo funcionan

Un webhook de Chaingateway es una suscripción que envía una solicitud HTTP POST a su URL cuando una transacción coincide con su filtro, por ejemplo un ingreso en una de sus direcciones. Así recibe avisos de pago sin consultas periódicas. Hay webhooks para Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON y Bitcoin, pero no para Solana.

Ciclo de vida de un webhook: se crea con un filtro, una transacción coincidente activa un POST a su URL, su servidor responde 200 y las entregas fallidas se listan y se reenvían a petición Crear un webhook POST /api/v2/{chain}/webhooks con url y unfiltro Una transacción coincide con el filtro Chaingateway envía la notificación por POST asu url Su receptor responde 200 y procesa el payload ¿Falló la entrega? GET .../webhooks/notifications/failed, despuésPOST .../notifications/{id}/retry
Las notificaciones fallidas no se reintentan automáticamente. Usted las lista y las reenvía.

Usted indica una URL pública y un filtro, y Chaingateway llama a la URL una vez por cada transacción coincidente. La llamada es un HTTP POST con un cuerpo JSON. Su aplicación lee el cuerpo y actúa, por ejemplo marcando un pedido como pagado. Cuando se usa para pagos, el patrón también se llama Instant Payment Notification, o IPN.

Cree el webhook poco antes de esperar el pago, con la dirección que lo recibirá. Cada notificación lleva los datos siguientes. El type es el tipo de activo, aquí una transferencia del token TRC20.

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"datetime": "2024-09-25 14:48:27",
"tokenid": null,
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

Necesita un receptor, es decir, un endpoint en su servidor que acepte solicitudes POST desde internet. El flujo de trabajo tiene cuatro pasos:

  1. Cree un endpoint receptor al que pueda llegar Chaingateway.
  2. Cree un webhook que apunte al receptor.
  3. Espere un evento de la blockchain que coincida.
  4. Lea el cuerpo de la solicitud y responda con el estado HTTP 200.

El receptor debe ser accesible públicamente. Revise cortafuegos, proxies inversos y reglas de red, porque una dirección privada o un puerto bloqueado hacen fallar todas las entregas. Si ha fijado un secreto personal, verifique la firma de cada solicitud antes de confiar en ella, como se describe en Seguridad de webhooks. Los receptores siguientes solo leen el cuerpo y responden.

from flask import Flask, request
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook_receiver():
data = request.get_json()
# Process the webhook data
# Update database, trigger notifications, execute business logic, etc.
return 'Webhook received successfully', 200
if __name__ == '__main__':
app.run()

Envíe una solicitud POST a /api/v2/{chain}/webhooks. El cuerpo necesita la url de su receptor y un filtro. Los campos del filtro son los siguientes.

CampoSignificado
urlObligatorio. La URL completa de su receptor, con la ruta.
fromDirección del remitente que se vigila.
toDirección del destinatario que se vigila.
contractaddressDirección del contrato de un token que quiere rastrear. No disponible en Bitcoin.
token_idID de token NFT.
typeTipo de activo. Ethereum y Arbitrum: ETH, ERC20, ERC721. Polygon: MATIC, ERC20, ERC721. BNB Smart Chain: BNB, BEP20, BEP721. TRON: TRX, TRC10, TRC20, TRC721.
referenceSu propia etiqueta, de hasta 255 caracteres.

Indique from o to. Si no indica ninguno, la API exige contractaddress y token_id. Los webhooks de Bitcoin solo aceptan url, from y to. Los formatos de dirección se validan, y una dirección que no coincide devuelve el estado 422 con el nombre del campo en errors.

Ventana de terminal
curl --request POST \
--url https://app.chaingateway.io/api/v2/ethereum/webhooks \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
"url": "https://example.com/webhook",
"contractaddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"type": "ERC20",
"reference": "order-1042"
}'

Una llamada correcta devuelve el estado 201 y el id del webhook:

{
"status": 201,
"ok": true,
"message": "Webhook created",
"data": {
"webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46"
}
}

Gestione los webhooks existentes con GET /api/v2/{chain}/webhooks para listarlos, GET .../webhooks/{id} para leer uno, PUT .../webhooks/{id} para cambiarlo y DELETE .../webhooks/{id} para eliminarlo. Elimine un webhook cuando haya llegado el pago, para que no siga coincidiendo con transferencias posteriores. PUT responde con el estado 404 y el mensaje Webhook not found cuando el id no existe.

Chaingateway no reintenta por sí mismo una entrega fallida. Las notificaciones fallidas se guardan, y usted las lee y las vuelve a enviar. Los dos endpoints son GET /api/v2/{chain}/webhooks/notifications/failed y POST /api/v2/{chain}/webhooks/notifications/{id}/retry. La lista está paginada con el parámetro de consulta page.

Cada entrada muestra el txid, la url de destino, la response guardada de su servidor y el número de attempts. Cuando inicia un reintento, la notificación sale de la lista de fallidas. Si el reintento también falla, vuelve a la lista. GET /api/v2/{chain}/webhooks/notifications lista todas las notificaciones, también las correctas. Ejecute una tarea pequeña que revise la lista de fallidas a intervalos y reintente lo que haya, y haga idempotente el receptor usando txid como clave, para que una notificación repetida no cause daño.

Solana no tiene endpoints de webhook. El archivo OpenAPI los define solo para Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON y Bitcoin. Para Solana, lea el saldo de la dirección receptora o liste las transacciones a intervalos fijos y compare el resultado con sus registros.