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.
¿Cómo funciona un webhook?
Sección titulada «¿Cómo funciona un webhook?»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}¿Qué necesito antes de crear un webhook?
Sección titulada «¿Qué necesito antes de crear un webhook?»Necesita un receptor, es decir, un endpoint en su servidor que acepte solicitudes POST desde internet. El flujo de trabajo tiene cuatro pasos:
- Cree un endpoint receptor al que pueda llegar Chaingateway.
- Cree un webhook que apunte al receptor.
- Espere un evento de la blockchain que coincida.
- 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()const express = require('express');
const app = express();app.use(express.json());
app.post('/webhook', (req, res) => { const data = req.body; // Process the webhook data // Update database, trigger notifications, execute business logic, etc. res.status(200).send('Webhook received successfully');});
app.listen(3000, () => { console.log('Webhook receiver is listening on port 3000');});<?php
$data = file_get_contents('php://input');$payload = json_decode($data, true);
// Process the webhook data// Update database, trigger notifications, execute business logic, etc.
http_response_code(200);echo 'Webhook received successfully';<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller{ /* * Register a route for it, for example: * Route::post('/webhook', [WebhookController::class, 'handle']); */ public function handle(Request $request) { $payload = $request->all();
// Process the webhook payload \Log::info('Webhook received: ', $payload);
return response()->json(['status' => 'success']); }}¿Cómo creo un webhook?
Sección titulada «¿Cómo creo un webhook?»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.
| Campo | Significado |
|---|---|
url | Obligatorio. La URL completa de su receptor, con la ruta. |
from | Dirección del remitente que se vigila. |
to | Dirección del destinatario que se vigila. |
contractaddress | Dirección del contrato de un token que quiere rastrear. No disponible en Bitcoin. |
token_id | ID de token NFT. |
type | Tipo de activo. Ethereum y Arbitrum: ETH, ERC20, ERC721. Polygon: MATIC, ERC20, ERC721. BNB Smart Chain: BNB, BEP20, BEP721. TRON: TRX, TRC10, TRC20, TRC721. |
reference | Su 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.
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"}'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/webhooks"
payload = { "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE", "url": "https://example.com/webhook", "contractaddress": "0xdac17f958d2ee523a2206206994597c13d831ec7", "type": "ERC20", "reference": "order-1042"}headers = { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_TOKEN"}
response = requests.post(url, json=payload, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'POST', url: 'https://app.chaingateway.io/api/v2/ethereum/webhooks', headers: {'Content-Type': 'application/json', Authorization: 'Bearer YOUR_API_TOKEN'}, data: { to: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE', url: 'https://example.com/webhook', contractaddress: '0xdac17f958d2ee523a2206206994597c13d831ec7', type: 'ERC20', reference: 'order-1042' }};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://app.chaingateway.io/api/v2/ethereum/webhooks', [ 'json' => [ 'to' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE', 'url' => 'https://example.com/webhook', 'contractaddress' => '0xdac17f958d2ee523a2206206994597c13d831ec7', 'type' => 'ERC20', 'reference' => 'order-1042', ], 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', ],]);
echo $response->getBody();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.
¿Qué ocurre cuando falla una entrega?
Sección titulada «¿Qué ocurre cuando falla una entrega?»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.
¿Cómo detecto ingresos en Solana?
Sección titulada «¿Cómo detecto ingresos en Solana?»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.
Fuentes
Sección titulada «Fuentes»- RFC 9110, HTTP Semantics define el método POST y los códigos de estado 2xx con los que responde un receptor.
- Transacciones de Ethereum describe los campos de transacción que aparecen en las notificaciones de las cadenas EVM.
- La documentación de transacciones de TRON describe los tipos de transacción que hay detrás de los valores
typede TRON.