Вебхуки

Узнайте, как функция вебхуков Chaingateway может предоставлять мгновенные уведомления о платежах на ваш сервер.

Введение

Вебхуки Chaingateway предоставляют мгновенные уведомления о платежах в реальном времени на эндпоинт ваших систем. Для этого вам следует создать вебхук непосредственно перед совершением платежа. Этот вебхук имеет несколько параметров фильтрации и предоставляет вам информацию о транзакции, как только транзакция подтверждена и соответствует вашим критериям фильтра.

Как работает вебхук

Вебхуки: Вебхуки — это способ для приложений отправлять уведомления в реальном времени другим приложениям или сервисам. В контексте блокчейна вебхуки можно использовать для получения уведомлений о различных событиях, таких как добыча новых блоков, подтверждение транзакций или срабатывание событий смарт-контрактов.

При настройке вебхука вы указываете URL-эндпоинт в вашем приложении, который будет получать уведомления. Каждый раз, когда происходит указанное событие, блокчейн-сеть отправит HTTP POST-запрос на ваш эндпоинт вебхука с соответствующими данными. Затем ваше приложение может обработать эти данные и предпринять соответствующие действия, например обновить базу данных, отправить уведомления или запустить другие процессы.

Instant Payment Notifications (IPN): IPN — это особый тип вебхука, используемый в контексте платёжных систем, включая платёжные системы на основе блокчейна. IPN обычно используются для получения уведомлений о событиях, связанных с платежами, таких как успешные платежи, неудачные платежи или возвраты.

Когда платёж совершается в блокчейн-сети, может быть запущено IPN-уведомление, чтобы сообщить вашему приложению о статусе платежа. Это позволяет вашему приложению обновлять свои внутренние записи, предоставлять мгновенную обратную связь пользователям или запускать дальнейшие действия на основе статуса платежа.

И вебхуки, и IPN необходимы для создания приложений реального времени, управляемых событиями, которые взаимодействуют с блокчейн-сетями. Они позволяют вашему приложению оставаться в курсе последних событий и предпринимать немедленные действия на их основе.

Пример сообщения вебхука

Наша система вебхуков отправляет сообщения в следующем формате

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

Рабочий процесс

Чтобы создать вебхук, вам нужно выполнить следующие шаги:

Создать приёмный эндпоинт, на который мы сможем отправлять вам вебхуки
Создать вебхук на Chaingateway, используя приёмный эндпоинт
Дождаться событий блокчейна
Обработать запрос и отправить правильный код ответа

Пример приёмника

Прежде чем создавать вебхук, вам сначала нужно настроить приёмник. Приёмник вебхука — это компонент или эндпоинт, который прослушивает входящие запросы вебхуков. Он выступает в роли приёмника или слушателя для событий, инициированных внешними системами или сервисами. Когда происходит событие вебхука, отправляющая система выполняет HTTP-запрос к URL приёмника вебхука, предоставляя данные, связанные с событием.

Роль приёмника вебхука заключается в обработке входящих запросов вебхуков. Обычно он выполняет действия на основе полученных данных, такие как обновление базы данных, запуск уведомления или выполнение конкретной бизнес-логики.

Чтобы настроить приёмник вебхука, вам нужно определить в вашем приложении эндпоинт, который может принимать входящие HTTP-запросы. Этот эндпоинт должен быть публично доступен, чтобы отправляющая система могла отправлять на него события вебхука. После настройки приёмника вы можете настроить отправляющую систему на отправку событий вебхука на URL приёмника.

::: tip Важно: Крайне важно, чтобы приёмники вебхуков были доступны извне. Это означает, что URL-адреса эндпоинтов, определённые в приёмниках вебхуков, должны быть публично доступны, чтобы отправляющие системы могли отправлять на них события вебхуков. Обязательно настройте свои сетевые параметры, файрволы и меры безопасности соответствующим образом, чтобы разрешить входящим HTTP-запросам достигать приёмников вебхуков. :::

#!/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']);
    }
}

Пример создания

После того как вы создали свой публичный приёмник вебхука, теперь мы можем создать вебхук.

Для создания вебхука у вас есть несколько параметров для фильтрации ваших релевантных событий.

from (string): Адрес отправителя.
to (string): Адрес получателя.
contractaddress (string): Адрес контракта, который вы хотите отслеживать.
token_id (string): ID NFT-токена.
type (string enum): Тип актива для отслеживания. Возможные значения для Ethereum: ETH, ERC20 или ERC721. Проверьте документацию для других сетей.

Вам также нужно добавить параметр url, который должен быть полностью квалифицированным доменным именем или IP-адресом с маршрутом к ранее созданному приёмному эндпоинту вебхука.

Это подразумевает обязательный набор из «url» и одного из «from» или «to». Остальное является необязательным.

примеры:

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();

Ответ будет выглядеть примерно так:

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