Saltearse al contenido

Crear webhooks de blockchain para depósitos

Para recibir notificaciones de depósitos de Chaingateway necesita dos partes: un endpoint receptor en su servidor y un webhook que crea con POST /api/v2/{chain}/webhooks. Cuando una transacción coincide con el filtro del webhook, Chaingateway envía una solicitud HTTP POST con los datos de la transacción a su endpoint. Este tutorial construye ambas partes para depósitos TRC20 entrantes en TRON. Los mismos pasos valen para Ethereum, BNB Smart Chain, Polygon, Arbitrum y Bitcoin. Solana no tiene webhooks.

Lea primero Webhooks si quiere conocer los conceptos y el formato del payload. Necesita un token de API del Inicio rápido.

Pasos del tutorial: escribir el receptor, hacerlo accesible desde internet, crear el webhook, enviar un payload de prueba y gestionar las entregas fallidas 1. Escribir el receptor endpoint POST que responde 200 2. Hacerlo accesible URL pública con HTTPS 3. Crear el webhook POST /api/v2/tron/webhooks con url y filtro 4. Probar con un payload curl contra su propio receptor 5. Gestionar los fallos listar las notificaciones fallidas yreenviarlas
Los pasos 1 y 2 van antes del paso 3, porque la URL debe funcionar cuando llegue el primer evento.

Un receptor es un endpoint de servidor que acepta solicitudes HTTP POST con un cuerpo JSON y responde con el estado 200. Mantenga el handler corto: guarde el payload, responda y haga el trabajo lento después, en una cola o en un proceso en segundo plano. Los ejemplos siguientes registran el payload y lo confirman.

const express = require('express');
const app = express();
const port = 3000;
app.use(express.json());
app.post('/webhook', (req, res) => {
console.log('Received webhook:', req.body);
res.status(200).send('Webhook received');
});
app.listen(port, () => {
console.log(`Webhook receiver listening at http://localhost:${port}`);
});

Chaingateway solo puede acceder a una URL pública. Durante el desarrollo, exponga su puerto local mediante un túnel y use la dirección HTTPS del túnel como url del webhook. Compruebe la firma de cada solicitud antes de actuar, como describe Seguridad de webhooks.

¿Cómo me suscribo a un evento de la blockchain?

Sección titulada «¿Cómo me suscribo a un evento de la blockchain?»

Envíe POST /api/v2/tron/webhooks con la url de su receptor y un filtro. El filtro decide qué transacciones activan una notificación.

  • url (obligatorio): la dirección de su receptor. Debe ser una URL válida.
  • from y to: la dirección del remitente y la del destinatario, en formato Tron. Al menos una de las dos es obligatoria, salvo que indique contractaddress y token_id.
  • contractaddress: el contrato del token que se vigila.
  • token_id: el identificador de un NFT.
  • type: uno de TRX, TRC10, TRC20, TRC721.
  • reference: su propia etiqueta de hasta 255 caracteres, por ejemplo un número de pedido.

El ejemplo vigila las transferencias TRC20 de un token a una dirección de depósito.

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

La respuesta tiene el estado 201 y el identificador del webhook en data.webhook. Guarde el identificador, porque lo necesita para actualizar o eliminar el webhook.

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

En otras cadenas cambian la ruta y los valores de type. Ethereum y Arbitrum aceptan ETH, ERC20 y ERC721, Polygon acepta MATIC, ERC20 y ERC721, BNB Smart Chain acepta BNB, BEP20 y BEP721, y Bitcoin solo recibe url, from y to. Las direcciones de las cadenas EVM deben cumplir 0x seguido de 40 caracteres hexadecimales. Para probar en una red de pruebas, añada la cabecera X-Network: testnet a la solicitud de creación.

¿Cómo pruebo el receptor antes de que llegue un depósito real?

Sección titulada «¿Cómo pruebo el receptor antes de que llegue un depósito real?»

Envíe una notificación de ejemplo a su propio endpoint con curl. El cuerpo siguiente tiene los mismos campos que una notificación real. Si su receptor lo registra y responde 200, el endpoint funciona. Después, envíe una transferencia pequeña en la red de pruebas a la dirección vigilada para ver el evento real.

Ventana de terminal
curl --request POST \
--url https://example.com/webhook \
--header 'Content-Type: application/json' \
--data '{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
"blocknumber": "65542464",
"datetime": "2024-09-25 14:48:27",
"tokenid": null,
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}'

¿Qué hago con las entregas fallidas y los webhooks antiguos?

Sección titulada «¿Qué hago con las entregas fallidas y los webhooks antiguos?»

Chaingateway no reintenta automáticamente las entregas fallidas. GET /api/v2/tron/webhooks/notifications/failed las lista, y POST /api/v2/tron/webhooks/notifications/{id}/retry reenvía una. Use GET /api/v2/tron/webhooks para listar sus webhooks, PUT /api/v2/tron/webhooks/{id} para modificar uno y DELETE /api/v2/tron/webhooks/{id} para eliminarlo. Elimine un webhook cuando haya cumplido su función, por ejemplo cuando haya llegado el pago de un pedido.

  • El receptor debe ser accesible públicamente y aceptar solicitudes HTTP POST.
  • Verifique el origen y la integridad de cada solicitud con la cabecera X-Signature.
  • Haga el receptor idempotente. Use el txid para detectar una notificación que ya procesó.
  • Guarde su token de API en un almacén de secretos, no en el código fuente del receptor.