Исходящие вебхуки (Webhooks)

Вебхуки позволяют вашему бэкенд-серверу мгновенно узнавать об изменениях статусов транзакций без необходимости постоянного опроса API (polling).

На данный момент поддерживается следующее событие:

• payment.succeeded — отправляется при успешной оплате и зачислении средств на баланс мерчанта.

---

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

1. Вы указываете ваш Webhook URL в настройках магазина в личном кабинете.
2. При наступлении события Datagio отправляет HTTP POST-запрос с JSON-телом на этот адрес.
3. Ваш сервер должен обработать запрос и вернуть любой HTTP-статус группы 2xx (например, 200 OK).

---

HTTP-заголовки запроса

Каждое уведомление сопровождается следующими заголовками:

• X-Webhook-Event: Название события (всегда payment.succeeded).
• X-Webhook-Signature: Шестнадцатеричная строка подписи тела запроса (SHA256 HMAC). Заголовок отправляется только в том случае, если в настройках магазина задан секретный ключ webhook_secret.

---

Проверка подписи (Безопасность)

Для защиты от подделки запросов проверяйте подпись X-Webhook-Signature. Она вычисляется как HMAC-SHA256 от сырого (raw) тела HTTP-запроса с использованием вашего секретного ключа webhook_secret.

Пример проверки подписи (Node.js)

const crypto = require('crypto');

function verifyWebhook(requestBody, signatureHeader, webhookSecret) {
  const computedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(requestBody) // requestBody должен быть сырой строкой/буфером
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computedSignature, 'utf8'),
    Buffer.from(signatureHeader, 'utf8')
  );
}

---

IP-адреса для фильтрации (IP Whitelisting)

Если ваш бэкенд использует сетевые фильтры или файрвол (Firewall) для ограничения входящего трафика, разрешите прием POST-запросов со следующих IP-адресов Datagio:

• 159.69.206.192 — Hetzner (Нюрнберг)
• 95.85.240.13 — ММТС-9 (Москва)
• 89.110.89.204 — DataPro (Москва)

---

Формат уведомления (JSON)

Тело запроса соответствует схеме PaymentSucceededEvent:

Поле	Тип	Описание
event	string	Название события (всегда "payment.succeeded").
data	object	Объект с данными транзакции.
data.payment_link_id	string (UUID)	Уникальный идентификатор оплаченной платёжной ссылки.
data.shop_id	string (UUID)	Идентификатор вашего магазина.
data.order_id	string | null	Ваш внешний ID заказа, переданный при создании ссылки.
data.amount	string	Цена товара в рублях. Всегда передаётся в виде строки с двумя знаками после точки (например, "1000.00").
data.merchant_credit	string	Сумма, зачисленная на ваш баланс после вычета комиссии платформы, ₽. Всегда передаётся в виде строки (например, "990.00").
data.status	string	Текущий статус оплаты (всегда "paid").
data.paid_at	string (date-time)	Дата и время оплаты в формате ISO 8601.

Пример тела вебхука

{
  "event": "payment.succeeded",
  "data": {
    "payment_link_id": "9c0526fe-0e45-423d-91ca-368e98b8ea96",
    "shop_id": "b79ffcef-5f6e-4adf-aa5f-e885b4d282d9",
    "order_id": "ORDER-12345",
    "amount": "1000.00",
    "merchant_credit": "990.00",
    "status": "paid",
    "paid_at": "2026-07-23T17:55:12Z"
  }
}

---

Гарантия доставки и повторы

• Подтверждение приёма: Ваш сервер должен ответить на вебхук HTTP-кодом из семейства 2xx. Любые другие коды (или отсутствие ответа) расцениваются как сбой.
• Политика повторных попыток: Если доставка не удалась, Datagio повторит отправку уведомления до 8 раз по экспоненциальной схеме (с интервалами, увеличивающимися вплоть до 1 часа между попытками). Полный цикл попыток занимает около суток.

[!IMPORTANT] Идемпотентность: Из-за возможных сетевых сбоев одно и то же уведомление может быть отправлено повторно. Ваша система обязана обрабатывать вебхуки идемпотентно на основе уникального идентификатора data.payment_link_id.