Webhooks

Descubra cómo la función de webhooks de Chaingateway puede ofrecer notificaciones de pago instantáneas a su servidor.

Introducción

Los webhooks de Chaingateway ofrecen notificaciones de pago instantáneas en tiempo real al endpoint de sus sistemas. Para ello, debe crear un webhook justo antes de que se realice el pago. Este webhook cuenta con varias opciones de filtro y le proporciona información de la transacción en cuanto se liquida una transacción que coincide con sus criterios de filtro.

Cómo funciona un webhook

Webhooks: Los webhooks son una forma de que las aplicaciones envíen notificaciones en tiempo real a otras aplicaciones o servicios. En el contexto de la blockchain, los webhooks se pueden usar para recibir notificaciones sobre varios eventos, como nuevos bloques minados, transacciones confirmadas o eventos de smart contracts activados.

Al configurar un webhook, proporciona un endpoint URL en su aplicación que recibirá las notificaciones. Cada vez que ocurra el evento especificado, la red blockchain enviará una solicitud HTTP POST a su endpoint de webhook con los datos relevantes. Su aplicación puede entonces procesar estos datos y realizar las acciones adecuadas, como actualizar una base de datos, enviar notificaciones o activar otros procesos.

Instant Payment Notifications (IPN): Las IPN son un tipo específico de webhook utilizado en el contexto de sistemas de pago, incluidos los sistemas de pago basados en blockchain. Las IPN se usan normalmente para recibir notificaciones sobre eventos relacionados con pagos, como pagos exitosos, pagos fallidos o reembolsos.

Cuando se realiza un pago en una red blockchain, se puede activar una IPN para notificar a su aplicación sobre el estado del pago. Esto permite a su aplicación actualizar sus registros internos, ofrecer retroalimentación instantánea a los usuarios, o activar acciones adicionales según el estado del pago.

Tanto los webhooks como las IPN son esenciales para crear aplicaciones en tiempo real y basadas en eventos que interactúan con redes blockchain. Permiten que su aplicación se mantenga actualizada con los últimos eventos y tome medidas inmediatas basadas en ellos.

Ejemplo de mensaje de webhook

Nuestro sistema de webhooks publica mensajes en este formato

{
  "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
}

Flujo de trabajo

Para crear un webhook, debe seguir estos pasos:

Crear un endpoint receptor al que podamos enviarle los webhooks
Crear un webhook en Chaingateway usando el endpoint receptor
Esperar los eventos de la blockchain
Consumir la solicitud y devolver el código de respuesta correcto

Ejemplo de receptor

Antes de crear un webhook, primero debe configurar un receptor. Un receptor de webhook es un componente o endpoint que escucha las solicitudes de webhook entrantes. Actúa como receptor o listener para eventos activados por sistemas o servicios externos. Cuando ocurre un evento de webhook, el sistema emisor realiza una solicitud HTTP a la URL del receptor de webhook, proporcionando los datos relacionados con el evento.

La función del receptor de webhook es gestionar y procesar las solicitudes de webhook entrantes. Normalmente realiza acciones basadas en los datos recibidos, como actualizar una base de datos, activar una notificación o ejecutar lógica de negocio específica.

Para configurar un receptor de webhook, debe definir un endpoint en su aplicación que pueda recibir solicitudes HTTP entrantes. Este endpoint debe ser públicamente accesible para que el sistema emisor pueda enviarle eventos de webhook. Una vez configurado el receptor, puede configurar el sistema emisor para que envíe los eventos de webhook a la URL del receptor.

::: tip Importante: Es fundamental que los receptores de webhook sean accesibles desde el exterior. Esto significa que las URL de endpoint definidas en los receptores de webhook deben ser públicamente accesibles para que los sistemas emisores puedan enviarles eventos de webhook. Asegúrese de configurar sus ajustes de red, cortafuegos y medidas de seguridad en consecuencia para permitir que las solicitudes HTTP entrantes lleguen a los receptores de webhook. :::

#!/bin/bash

# Define the endpoint URL
ENDPOINT_URL="https://example.com/webhook"

# Start a local server to receive the webhook
nc -l -p 8080 > webhook_payload.json &

# Print the server's PID
echo "Webhook receiver is running with PID: $!"

# Wait for the webhook payload to be received
sleep 5

# Read the received payload from the file
PAYLOAD=$(cat webhook_payload.json)

# Process the webhook data
# Update database, trigger notifications, execute business logic, etc.

# Send the response back to the sender
echo "Webhook received successfully" | curl -X POST -d @- $ENDPOINT_URL

# Clean up the temporary files
rm webhook_payload.json

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook_receiver():
    data = request.json()
    # Process the webhook data
    # Update database, trigger notifications, execute business logic, etc.
    return 'Webhook received successfully'

if __name__ == '__main__':
    app.run()

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
    const data = req.body;
    // Process the webhook data
    // Update database, trigger notifications, execute business logic, etc.
    res.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
{
    /*
    * you should register a route for it like
    * Route::post('/webhook', [WebhookController::class, 'handle']);
    */
    public function handle(Request $request)
    {
        // Log the webhook payload for debugging
        \Log::info('Webhook received: ', $request->all());

        // Process the webhook payload
        $eventType = $request->header('X-Event-Type');
        $payload = $request->all();

       // Do something with this webhook receiver

        // Respond to the webhook sender
        return response()->json(['status' => 'success']);
    }
}

Ejemplo de creación

Una vez creado su receptor de webhook público, ya podemos crear el webhook.

Para crear un webhook, dispone de varias opciones para filtrar sus eventos relevantes.

from (string): La dirección del remitente.
to (string): La dirección del destinatario.
contractaddress (string): La dirección de un contrato que desea rastrear.
token_id (string): Un ID de token NFT.
type (string enum): El tipo de activo a rastrear. Los valores posibles para Ethereum son ETH, ERC20 o ERC721. Consulte la documentación para otras chains.

También debe añadir el parámetro url, que debe ser un nombre de dominio totalmente cualificado o una dirección IP con la ruta hacia el endpoint receptor de webhook que creó anteriormente.

Esto implica un conjunto requerido de «url» y uno de «from» o «to». El resto es opcional.

ejemplos:

curl --request POST \
  --url https://api.chaingateway.io/api/v2/ethereum/webhooks \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "from": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "url": "http://vonrueden.com/",
  "contractaddress": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "token_id": null,
  "type": "ERC20"
}'

import requests

url = "https://api.chaingateway.io/api/v2/ethereum/webhooks"

payload = {
    "from": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
    "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
    "url": "http://vonrueden.com/",
    "contractaddress": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
    "token_id": None,
    "type": "ERC20"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_SECRET_TOKEN"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.chaingateway.io/api/v2/ethereum/webhooks',
  headers: {'Content-Type': 'application/json', Authorization: 'YOUR_SECRET_TOKEN'},
  data: {
    from: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    to: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    url: 'http://vonrueden.com/',
    contractaddress: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    token_id: null,
    type: 'ERC20'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.chaingateway.io/api/v2/ethereum/webhooks', [
  'body' => '{
  "from": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "url": "http://vonrueden.com/",
  "contractaddress": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "token_id": null,
  "type": "ERC20"
}',
  'headers' => [
    'Authorization' => 'YOUR_SECRET_TOKEN',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'YOUR_SECRET_TOKEN',
    'Content-Type' => 'application/json',
])->post('https://api.chaingateway.io/api/v2/ethereum/webhooks', [
    'from' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    'to' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    'url' => 'http://vonrueden.com/',
    'contractaddress' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    'token_id' => null,
    'type' => 'ERC20',
]);

echo $response->body();

La respuesta se verá entonces así:

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