POST /apiv2/reports/webhooks

Зареєструйте URL, і NETTS викличе його, коли звіт буде готовий, замість того, щоб ви постійно опитували статус.

Ці кінцеві точки є окремими від вебхуків замовлень. Реєстрація там не підписує вас на сповіщення про звіти, і навпаки. Формат передачі даних — підпис, заголовки, поведінка повторних спроб — ідентичний, тому обробник, написаний для одного, працюватиме і для іншого.

Базовий URL ендпоінта

https://netts.io/apiv2/reports/webhooks

Заголовки запиту

Заголовок	Обов'язковий	Опис
X-API-KEY	так	Ключ API з панелі керування
X-Real-IP	так	Адреса з білого списку ключа

Основний та резервний

До двох кінцевих точок на акаунт. primary отримує все. backup використовується лише після того, як вичерпано спроби доставки на основний, — і він підписується власним секретом, а не секретом основного.

Реєстрація

curl -s -X POST 'https://netts.io/apiv2/reports/webhooks' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/netts/reports", "role": "primary"}'

{
  "status": "success",
  "code": 10000,
  "data": {
    "id": 1,
    "url": "https://example.com/netts/reports",
    "role": "primary",
    "is_active": true,
    "created_at": "2026-09-06 17:05:12+00:00",
    "updated_at": "2026-09-06 17:05:12+00:00",
    "secret": "whsec_<64 hex characters>"
  }
}

Секрет відображається один раз, тут. Він більше ніколи не повертається — ні списком, ні кінцевою точкою читання. Збережіть його, коли отримаєте. Якщо його втрачено, згенеруйте новий:

curl -s -X POST 'https://netts.io/apiv2/reports/webhooks/1/rotate-secret' \
  -H 'X-API-KEY: your-api-key' -H 'X-Real-IP: 203.0.113.10'

Ротація набуває чинності негайно, і старий секрет перестає проходити перевірку, тому спочатку розгорніть нове значення, якщо ви не можете допустити перерви в роботі.

Керування

Метод	Шлях	Дія
GET	/apiv2/reports/webhooks	список ваших, без секретів
GET	/apiv2/reports/webhooks/{id}	прочитати один
PATCH	/apiv2/reports/webhooks/{id}	змінити url або призупинити за допомогою is_active: false
DELETE	/apiv2/reports/webhooks/{id}	видалити його

URL має бути публічним HTTPS. Loopback, приватні та link-local адреси відхиляються, як і облікові дані всередині URL. Будь-яка відхилена адреса повертається як 422 із зазначенням причини. Перевірка виконується повторно безпосередньо перед кожною доставкою, тому кінцева точка, яка згодом резолвиться в приватну адресу, перестає отримувати сповіщення.

Що ми надсилаємо

{
  "event": "report.ready",
  "delivery_id": 4,
  "order_id": "REPxxxxxxxxxxxx",
  "order_type": "statement",
  "client_request_id": "stmt-2026-09-usdt",
  "status": "done",
  "format": "csv",
  "download_url": "/apiv2/reports/REPxxxxxxxxxxxx/download",
  "expires_at": "2026-10-06 15:48:04+00:00",
  "artifact": { "sha256": "…", "size_bytes": 696 },
  "confirmed_at": "2026-09-06T15:48:04Z"
}

Поле	Опис
event	report.ready — ключ маршрутизації для вашого обробника
delivery_id	Ключ дедуплікації. Також надсилається як заголовок X-Netts-Delivery
order_id	Номер замовлення, який ви отримали, коли поставили звіт у чергу
order_type	statement або balance_at_date
download_url	Шлях для завантаження файлу, відносний до https://netts.io
artifact.sha256	Контрольна сума, щоб ви могли перевірити те, що завантажили
confirmed_at	UTC

Усі часові мітки вказані за UTC.

Перевірка підпису

X-Netts-Signature: sha256=<hex>
X-Netts-Timestamp: <unix seconds>
X-Netts-Delivery:  <delivery_id>

Підпис — це HMAC-SHA256 від "<timestamp>." + raw body, обчислений із секретом кінцевої точки, яка отримала запит. Порівнюйте за сталий час і відхиляйте будь-що, чия часова мітка виходить за межі вікна ±5 хвилин.

import hmac, hashlib, time

def verify(raw_body: bytes, sig_header: str, ts_header: str, secret: str) -> bool:
    if abs(time.time() - int(ts_header)) > 300:      # anti-replay
        return False
    signed = f"{ts_header}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig_header)

Підписуйте секретом того URL, на який надійшов запит: основний та резервний мають різні секрети.

Доставка здійснюється принаймні один раз (at-least-once)

Втрачена відповідь спричиняє повторну спробу, тому та сама подія може надійти двічі.

1. Дедуплікуйте за delivery_id. Повтор має бути операцією без дії (no-op) на вашому боці.
2. Перевіряйте підпис до виконання дій, а не після.
3. Відповідайте 2xx лише після того, як ви зберегли подію. Будь-що інше або тайм-аут розцінюється як помилка і призводить до повторної спроби.

Повторні спроби на одну кінцеву точку виконуються через 1 хвилину, 5 хвилин, 15 хвилин, 1 годину, 6 годин і 24 години — загалом шість спроб, які охоплюють трохи більше ніж 31 годину. Коли вони вичерпані, і ви зареєстрували backup, доставка переходить туди, а розклад починається заново з власним секретом резервної точки. delivery_id залишається незмінним протягом усього часу, тому подія, яка зазнала невдачі на основній точці та пройшла успішно на резервній, все одно є однією подією.

Перенаправлення (redirects) не підтримуються.

Ліміти запитів

10 запитів на секунду на кінцеву точку, спільно для всіх клієнтів.

Помилки

Реєстрація повертає 201, видалення повертає 204 без тіла, все інше — 200.

HTTP	Значення
401	ключ відсутній або недійсний, або IP-адреси джерела немає в білому списку
404	такої кінцевої точки немає у вашому акаунті
409	запитана роль уже зайнята — role primary is already taken
422	URL було відхилено, або тіло PATCH не містило жодних змін
429	перевищено ліміт запитів

Відхилений URL повертається як 422 з чітко зазначеною причиною, тому ви можете показати її тому, хто її ввів:

{"status": "error", "code": -4, "msg": "url: Value error, invalid webhook_url: resolved address 127.0.0.1 is not public"}

Формулювання такі: only https:// URLs are allowed, credentials in URL are not allowed, та resolved address <ip> is not public. Остання адреса резолвиться під час реєстрації та повторно безпосередньо перед кожною доставкою, тому ім'я хоста, яке пізніше вказує на приватну адресу, перестає отримувати сповіщення.

Пов'язане

• Файли виписок — замовлення звіту, що запускає це сповіщення
• Вебхуки замовлень — окремий реєстр для подій Energy, Bandwidth та активації