← Blog
10 min de lectura
|
Publicado
|
Actualizado

Webhooks para depósitos cripto: cómo funcionan

Cómo detecta un webhook un depósito cripto entrante: webhook frente a polling, campos del payload, verificación de la firma HMAC y notificaciones perdidas.

Capítulos
C
Chaingateway Team
Expertos en blockchain

Revisado por Maurice Sobiera

Un webhook es una solicitud HTTP que un servicio envía a su servidor cuando ocurre un evento. En los depósitos cripto, el evento es una transacción que coincide con una dirección vigilada. Chaingateway envía los detalles a su endpoint, y su código acredita al cliente. Esto sustituye el polling repetido de una API blockchain en busca de transacciones nuevas.

¿Qué es un webhook?

Un webhook es un callback sobre HTTP. Usted da al emisor una URL, y el emisor hace una solicitud POST a esa URL cuando ocurre un evento predefinido. El cuerpo de la solicitud es el payload. Piense en la URL como un número de teléfono al que el emisor llama cada vez que ocurre algo.

Los webhooks y las API son dos formas de intercambiar datos. Con una API usted extrae: su código pide datos según una programación y comprueba si algo ha cambiado. Con un webhook el proveedor empuja: le avisa en el momento del evento. El modelo push ahorra solicitudes y acorta el retraso. El modelo pull sigue teniendo su papel, porque un webhook solo le dice que ha ocurrido algo. Si necesita el registro completo o quiere comprobarlo, consulta la API.

Webhook o polling: ¿cuál debo usar para los depósitos?

Use webhooks para enterarse rápido de un depósito, y la API para verificarlo y conciliarlo. Los dos funcionan bien juntos.

EnfoquePunto fuertePunto débil
Polling de la APIUsted controla el momento y puede retomar tras una caídaDesperdicia solicitudes, y el retraso es tan largo como su intervalo
WebhookNotificación poco después de detectar la transacciónSe puede perder una notificación si su endpoint está caído

En Chaingateway, los webhooks están disponibles para Bitcoin, Ethereum, BNB Smart Chain, Tron, Polygon y Arbitrum. Solana no tiene webhooks, así que allí se consultan las transacciones.

¿Cómo configuro un webhook de depósitos?

Cree un endpoint receptor y después registre un webhook para la dirección que quiere vigilar. El endpoint debe ser accesible desde Internet público. No necesita permitir las direcciones IP de Chaingateway, porque el servicio llama a su URL pública como cualquier otro cliente.

Un webhook necesita una url y al menos uno de from o to. Los filtros opcionales son contractaddress, token_id y type, que en Ethereum es ETH, ERC20 o ERC721. También puede definir una reference de hasta 255 caracteres, por ejemplo su número de pedido. Esta solicitud vigila los depósitos de un token ERC-20 (aquí el contrato de USDT) a una dirección.

Terminal window
curl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
"url": "https://example.com/hooks/deposits",
"type": "ERC20",
"contractaddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"reference": "order-1042"
}'

Una llamada correcta devuelve el estado 201 y el ID del webhook en data.webhook. Cree el webhook antes de que el cliente pague, para que el pago no pueda producirse antes de que exista la vigilancia.

¿Qué contiene la notificación?

Cada POST contiene los campos que necesita para asociar el pago con un pedido. Este ejemplo procede de la documentación de Chaingateway para una transferencia 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
}

El txid identifica la transacción, y webhook_id le indica qué vigilancia se activó. Guarde el txid con un índice único. Si la misma notificación llega dos veces, la segunda inserción falla y usted la omite.

¿Cómo verifico que una notificación es auténtica?

Compruebe la cabecera X-Signature antes de fiarse del payload. Chaingateway calcula un HMAC con SHA-256 sobre el txid, usa su secreto personal como clave y envía el resultado codificado en Base64. HMAC está definido en la RFC 2104. Su servidor repite el cálculo y compara ambos valores con una comparación de tiempo constante.

Usted define el secreto personal en los ajustes de su perfil. Una vez que existe un secreto, la cabecera se añade a todos los webhooks salientes. La documentación de la firma incluye código de verificación para Python, Java, PHP y JavaScript.

¿Cómo es un receptor mínimo?

Un receptor verifica la firma, registra el evento una sola vez y responde rápido. Este ejemplo con Express guarda en memoria los ID de transacción ya vistos para ser breve. En producción, use una tabla de base de datos con un índice único sobre txid.

const crypto = require('crypto');
const express = require('express');
const app = express();
const seen = new Set();
app.post('/hooks/deposits', express.json(), (req, res) => {
const { txid, to, amount } = req.body;
const expected = crypto
.createHmac('sha256', process.env.PERSONAL_SECRET)
.update(txid)
.digest('base64');
const received = req.get('X-Signature') || '';
const valid =
expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
if (!valid) return res.sendStatus(401);
if (!seen.has(txid)) {
seen.add(txid);
// credit the order that belongs to the address `to` for `amount`
}
res.sendStatus(200);
});
app.listen(3000);

Pruebe primero el receptor en una testnet. Envíe la cabecera X-Network: testnet al crear el webhook y después haga una pequeña transferencia de prueba a la dirección vigilada. La notificación debe llegar con el txid de esa transferencia. La documentación aconseja crear el webhook justo antes de realizar el pago, así que créelo cuando entregue la dirección.

¿Qué ocurre si mi servidor está caído?

La notificación no se vuelve a enviar automáticamente. Si su endpoint no acepta una notificación, esta aparece en la lista de notificaciones fallidas en GET /api/v2/{chain}/webhooks/notifications/failed. Usted activa una nueva entrega para cada entrada con POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Si el reintento falla, la entrada vuelve a la lista.

Devuelva un estado de éxito en cuanto haya guardado el evento, y haga el trabajo lento después. La RFC 9110 define la clase 2xx de códigos de estado como que la solicitud fue recibida y aceptada. Revise la lista de fallos con regularidad y concilie sus registros con la API para que una laguna no pase inadvertida. La guía de entrega de webhooks trata los duplicados y el orden con más detalle.

Cómo escribimos estos artículos

¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.

C
Chaingateway Team
Expertos en blockchain

El equipo de Chaingateway se dedica a simplificar la integración blockchain para desarrolladores de todo el mundo.