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

Вебхуки позволяют бэкенду узнавать об оплате без постоянного опроса API.

Событие:

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

---

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

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

---

HTTP-заголовки

• X-Webhook-Event: payment.succeeded
• X-Webhook-Signature: hex HMAC-SHA256 тела запроса (если задан webhook_secret)

Те же значения дублируются в Datagio-Event и Datagio-Signature.

---

Проверка подписи

Подпись: hex(HMAC-SHA256(raw_body, webhook_secret)).

Пример (Node.js)

const crypto = require('crypto');

function verifyWebhook(requestBody, signatureHeader, webhookSecret) {
  const computedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(requestBody)
    .digest('hex');

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

---

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

Если фильтруете входящий трафик, разрешите POST с:

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

---

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

Поле	Тип	Описание
event	string	"payment.succeeded"
data.payment_link_id	string (UUID)	ID оплаченной ссылки
data.id	string (UUID)	То же, что payment_link_id
data.shop_id	integer	ID магазина
data.order_id	string | null	Ваш внешний ID заказа
data.amount	string	Цена товара, ₽ ("1000.00")
data.merchant_credit	string	Зачислено после комиссии, ₽
data.status	string	"paid"
data.paid_at	string	Оплата, RFC3339 (+03:00)

{
  "event": "payment.succeeded",
  "data": {
    "payment_link_id": "9c0526fe-0e45-423d-91ca-368e98b8ea96",
    "id": "9c0526fe-0e45-423d-91ca-368e98b8ea96",
    "shop_id": 1,
    "order_id": "ORDER-12345",
    "amount": "1000.00",
    "merchant_credit": "950.00",
    "status": "paid",
    "paid_at": "2026-09-17T18:00:00+03:00"
  }
}

---

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

• Успех — любой HTTP 2xx.
• Иначе до 8 попыток с экспоненциальным backoff.
• Обрабатывайте идемпотентно по data.payment_link_id.

[!IMPORTANT] Одно и то же уведомление может прийти повторно. Не зачисляйте заказ дважды.