Webhooks

Вступ

Вихідні вебхуки AOA: платформа сама повідомляє вашу систему про оплати, повернення та скасування подій.

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

Найважливіше — скасування подій

Опитування статусу замовлення покриває оплату, але не те, що стається згодом. Подію можуть скасувати через тиждень після покупки — а ніхто не опитує статус давно купленого квитка. Без вебхука ваша система про це просто не дізнається.

Як підключити

Потрібен API-ключ із дозволом webhooks:write. Зареєструйте адресу, куди слати запити, і перелічіть події:

cURL

curl -X POST https://aoa.com.ua/api/v1/webhooks \
  -H "Authorization: Bearer aoa_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/aoa",
    "events": ["order.paid", "event.cancelled"]
  }'

JSON

{
  "data": {
    "id": "8f3c1a92-…",
    "url": "https://example.com/hooks/aoa",
    "events": ["order.paid", "event.cancelled"],
    "secret": "whsec_9Kq2mR7vXp4nT8wL5yB1zC4d",
    "createdAt": "2026-07-30T12:00:00.000Z"
  }
}

Секрет показується один раз

Поле secret повертається тільки у відповіді на створення — далі ми зберігаємо його зашифрованим і показати повторно не можемо. Збережіть його одразу: ним ви перевіряєте підпис кожного запиту.

Один ключ може мати до 10 адрес — зручно, коли тестове й бойове середовища слухають різні хости.

Вимоги до адреси

Тільки https і порт 443 або 8443.
Хост має бути публічним. Адреси у внутрішніх мережах — localhost, 10.x, 192.168.x, 169.254.x — відхиляються. Перевірка робиться і при реєстрації, і перед кожною доставкою: якщо домен пізніше почне резолвитись у внутрішню адресу, ми припинимо на нього слати.
Для локальної розробки використовуйте тунель на кшталт ngrok або адресу від Make чи webhook.site — вони публічні.

Як виглядає доставка

HTTP

POST /hooks/aoa HTTP/1.1
Content-Type: application/json
AOA-Signature: t=1800000000,v1=5f2a…
AOA-Delivery-Id: 3d9f7c21-…
AOA-Event-Type: order.paid

{
  "id": "3d9f7c21-…",
  "type": "order.paid",
  "createdAt": "2026-07-30T12:00:00.000Z",
  "data": {
    "paymentId": "d3f1a2b4-…",
    "eventId": "a1b2c3",
    "status": "SUCCESS",
    "amountMinor": 90000,
    "currency": "UAH",
    "attendeeId": "clx9attendee01"
  }
}

Заголовок	Призначення
`AOA-Signature`	Підпис тіла. Обовʼязково перевіряйте — див. Перевірка підпису
`AOA-Delivery-Id`	Ідентифікатор доставки. При повторі той самий — за ним дедуплікуйте
`AOA-Event-Type`	Тип події — дублює поле type в тілі, зручно для маршрутизації

Що має робити ваш обробник

Відповідати швидко. Будь-який код 2xx означає «прийнято». Ми чекаємо відповідь до 10 секунд — важку роботу робіть після відповіді, не до неї.
Бути готовим до повторів. Та сама подія може прийти двічі: ми не отримали відповідь вчасно, хоча ви її обробили. Звіряйтесь із AOA-Delivery-Id.
Перевіряти підпис до обробки. Адреса вашого обробника рано чи пізно стане відомою — підпис єдине, що відрізняє наш запит від чужого.

Що буде, якщо ваш сервер лежить

Ми повторюємо доставку з наростаючими паузами: через хвилину, 5 хвилин, 30 хвилин, 2 години і 6 годин. Разом близько девʼяти годин — цього вистачає, щоб пережити нічний деплой чи аварію.

Якщо адреса не відповідає дуже довго, ми вимикаємо її автоматично, щоб не тримати чергу мертвих запитів. Те саме стається одразу, без повторів, якщо адреса почала резолвитись у внутрішню мережу — причина буде видна у полі lastError останньої доставки.

Побачити стан можна у GET /api/v1/webhooks — поле disabledAt. Увімкнути назад:

cURL

curl -X PATCH https://aoa.com.ua/api/v1/webhooks/{id} \
  -H "Authorization: Bearer aoa_live_…" \
  -H "Content-Type: application/json" \
  -d '{"isActive": true}'

Без коду

Писати обробник не обовʼязково: вебхуки AOA працюють з Make, Zapier і n8n напряму. Готові рецепти — Make, Zapier, n8n.