Вебхуки

Когда платёж приходит в итоговый статус, мы отправляем подписанный POST-запрос на ваш сервер. Проверьте подпись — и обновляйте заказ.

Куда приходят уведомления

  • На адрес по умолчанию из настроек ключа.
  • Или на webhook_url, переданный при создании платежа, — для этого платежа он главнее.
  • Адрес должен быть публичным. Внутренние и частные адреса отклоняются, повторов по ним нет.

Когда отправляем

При итоговых статусах платежа: paid, expired, canceled, failed и manual_confirmation.

Что отправляем

Тело
{
  "event": "invoice.status_changed",
  "payment_id": "pay_3f9a1c2b7d4e5f60",
  "bill_uid": "3f9a1c2b-7d4e-5f60-…",
  "order_id": "order_123",
  "status": "paid",
  "amount": 100.0,
  "currency": "USDT",
  "customer_email": "",
  "customer_name": "",
  "timestamp": 1763380800
}

При статусе paid в теле есть и разбивка комиссии: commission, commission_rate, commission_fixed, net_amount и net_currency.

ЗаголовокЗначение
X-Webhook-Signaturesha256=<hex>: подпись тела, см. ниже
X-Webhook-Eventacquiring.invoice_status_changed
X-Webhook-IdНомер уведомления. Одинаковый при каждом повторе — по нему отбрасывайте дубли
X-Webhook-TimestampВремя события, секунды Unix. Подписью не защищён
User-AgentTeleportExchange-Webhook/1.0

Как проверить подпись

  • Подпись — HMAC-SHA256 от сырого тела запроса, в шестнадцатеричном виде строчными буквами, в формате sha256=<hex>.
  • Ключ — ваш секрет вебхуков ровно в том виде, в каком его показывают настройки ключа: строка целиком, вместе с префиксом whsec_.
  • Считайте подпись по байтам тела в том виде, в каком они пришли, до разбора JSON: повторная сериализация меняет байты и ломает подпись.
  • Сравнивайте за постоянное время. Отклоняйте запрос, если заголовка нет или он не совпал.
  • Чтобы отсекать слишком старые уведомления, используйте поле timestamp внутри тела — оно подписано.
Python
import hashlib, hmac

def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")
Node.js
import crypto from "node:crypto"

function isValid(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(header || "")
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Каким ключом подписано

Секретом того API-ключа, которым создан платёж. Для платежей, созданных до появления подписи: ключом того же счёта, иначе ключом с тем же адресом вебхука, иначе самым старым активным ключом. Если активных ключей нет совсем, уведомление уходит без подписи.

Доставка и повторы

  • Ответьте любым 2xx в течение 10 секунд. Всё остальное считается неудачной попыткой.
  • Неудачную доставку повторяем через 30 секунд и ещё раз через 5 минут — всего три попытки, с тем же телом и тем же X-Webhook-Id.
  • После третьей неудачи уведомление помечается как не доставленное и автоматически больше не отправляется. На сам платёж это не влияет: его статус всегда можно получить через API.

WooCommerce

Нужен плагин версии 1.1.0 или новее с заполненным полем Webhook Secret. Секрет скопируйте из настроек ключа (начинается с whsec_). Плагин проверяет каждое уведомление и отклоняет с ответом 403 те, у которых нет подписи, она неверна или поле секрета пустое. Скачать — один PHP-файл в wp-content/plugins/: английская версия https://gate.teleport.ltd/api/crypto-acquiring/developers/download/woocommerce/, русская https://gate.teleport.ltd/api/crypto-acquiring/developers/download/woocommerce-ru/.

Статус платежа можно проверить в любой момент
curl https://gate.teleport.ltd/api/crypto-acquiring/v1/invoice/<bill_uid>/ \
  -H "X-API-Key: <YOUR_API_KEY>"

Teleport

Run your financial operations from one place.

Tell us how your business works. We'll show you the platform, map your current financial flow and discuss the right setup.