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.
¿Cómo escribo un receptor de webhooks?
Sección titulada «¿Cómo escribo un receptor de webhooks?»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}`);});from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])def webhook(): data = request.get_json() print('Received webhook:', data) return jsonify({'status': 'Webhook received'}), 200
if __name__ == '__main__': app.run(port=3000)<?phpif ($_SERVER['REQUEST_METHOD'] === 'POST') { $data = file_get_contents('php://input'); $json = json_decode($data, true); file_put_contents('php://stderr', print_r($json, TRUE)); http_response_code(200); echo json_encode(['status' => 'Webhook received']);}<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller{ // Register the route in routes/api.php: // Route::post('/webhook', [WebhookController::class, 'handleWebhook']); public function handleWebhook(Request $request) { $data = $request->all(); file_put_contents('php://stderr', print_r($data, TRUE)); return response()->json(['status' => 'Webhook received'], 200); }}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.fromyto: la dirección del remitente y la del destinatario, en formato Tron. Al menos una de las dos es obligatoria, salvo que indiquecontractaddressytoken_id.contractaddress: el contrato del token que se vigila.token_id: el identificador de un NFT.type: uno deTRX,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.
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"}'import requests
url = "https://app.chaingateway.io/api/v2/tron/webhooks"payload = { "url": "https://example.com/webhook", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "type": "TRC20", "reference": "order-1042"}headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'}
response = requests.post(url, json=payload, headers=headers)print(response.json())const axios = require('axios');
const url = 'https://app.chaingateway.io/api/v2/tron/webhooks';const payload = { url: 'https://example.com/webhook', to: 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', contractaddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', type: 'TRC20', reference: 'order-1042'};const headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'};
axios.post(url, payload, { headers }) .then(response => { console.log(response.data); }) .catch(error => { console.error(error.response?.data ?? error); });<?phprequire 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client();$response = $client->post('https://app.chaingateway.io/api/v2/tron/webhooks', [ 'headers' => [ 'Accept' => 'application/json', 'Authorization' => 'Bearer YOUR_API_TOKEN', ], 'json' => [ 'url' => 'https://example.com/webhook', 'to' => 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', 'contractaddress' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', 'type' => 'TRC20', 'reference' => 'order-1042' ]]);
echo $response->getBody();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.
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.
Información importante
Sección titulada «Información importante»- 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
txidpara 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.
Fuentes
Sección titulada «Fuentes»- RFC 9110, HTTP Semantics define el método POST y los códigos de estado que usa el receptor.
- TRON TRC20 protocol interface define los eventos de token en los que se basan las notificaciones TRC20.
- Ethereum token standard EIP-20 define lo mismo para ERC-20 en las cadenas EVM.