# Вебхуки (/uk/webhooks)



Вебхуки сповіщають ваш сервер про зміни у вашій організації Tapaya. Використовуйте ту саму інтеграцію для платежів у торговій точці та онлайн-платежів незалежно від платіжного процесора.

## Як це працює [#how-it-works]

<WebhookLifecycle senderLabel="Tapaya" receiverLabel="Ваш сервер" label="Підтверджена зміна ставить подію в чергу. Tapaya підписує та надсилає її. Ваш обробник перевіряє та зберігає її. Відповідь 2xx підтверджує доставку; у разі помилки повторюється крок надсилання, щонайбільше 12 спроб, після чого доставка припиняється." event="Збережена зміна" queue="Подія в черзі" send="Підписаний POST" receive="Перевірити та зберегти" delivered="Доставлено" />

Налаштуйте одну цільову HTTPS-адресу для кожної організації та виберіть потрібні події. Tapaya надсилає HTTP `POST` зі знімком у форматі JSON і підписом. Перевірте підпис, збережіть подію та поверніть успішну відповідь перед виконанням власної бізнес-логіки.

Ви можете підписатися на окремі типи або на всі підтримувані типи. Підписка на всі типи також отримуватиме нові підтримувані типи в майбутньому, тому ігноруйте типи, які ваш застосунок не розпізнає.

## Швидка інтеграція [#quick-integration]

<div className="fd-steps [&_h3]:fd-step">
  ### Збережіть цільову адресу [#save-a-destination]

  У Platform відкрийте **API Keys**, потім **Webhooks**. Введіть свою HTTPS URL-адресу, виберіть потрібні події та збережіть. Одразу скопіюйте signing secret (ключ підпису); він показується лише один раз. Див. [Налаштування](/webhooks/configuration).

  ### Перевіряйте кожен запит [#verify-each-request]

  Обчисліть HMAC-SHA256 від часової мітки, крапки та початкового тіла за допомогою свого signing secret і порівняйте результат із `X-Tapaya-Signature`. Див. [Перевірте підпис](/webhooks/receiving#check-the-signature).

  ### Збережіть подію, потім поверніть 2xx [#store-the-event-then-return-2xx]

  Збережіть подію з унікальним `id`, дайте відповідь `2xx` протягом 10 секунд і обробіть її після цього. Див. [Збережіть і підтвердьте](/webhooks/receiving#store-and-acknowledge).

  ### Надішліть тестовий вебхук [#send-a-test-webhook]

  На тій самій сторінці скористайтеся тестовою дією, щоб надіслати підписаний `webhook.test`. Див. [Надішліть тестовий вебхук](/webhooks/receiving#send-a-test-webhook).
</div>

## Оболонка події [#event-envelope]

Кожна подія використовує цю спільну структуру. Знімок ресурсу всередині `data` залежить від типу події.

```json
{
  "id": "019a0000-0000-7000-8000-000000000001",
  "type": "payment.succeeded",
  "apiVersion": "1",
  "organizationId": "019a0000-0000-7000-8000-000000000002",
  "merchantId": "019a0000-0000-7000-8000-000000000005",
  "createdAt": "2026-10-30T12:00:00.000000Z",
  "data": {
    "payment": {
      "id": "019a0000-0000-7000-8000-000000000003",
      "token": "example_payment_token",
      "merchantId": "019a0000-0000-7000-8000-000000000005",
      "status": "success",
      "statusId": 2,
      "requestedAmount": 10000,
      "requestedCurrencyId": 203,
      "settlementAmount": 10000,
      "settlementCurrencyId": 203
    }
  }
}
```

| Поле             | Значення                                                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Унікальний ID події. Використовуйте його для дедуплікації доставок. Повторні спроби зберігають той самий ID.               |
| `type`           | Назва події з [каталогу подій](/webhooks/events).                                                                          |
| `apiVersion`     | Ідентифікатор схеми payload, наразі рядок `"1"`.                                                                           |
| `organizationId` | Організація, якій належить подія. Перевірте, чи вона відповідає вашій інтеграції.                                          |
| `merchantId`     | Мерчант, якому належить ресурс. Може бути `null` для старіших платежів із невизначеним власником або діагностичного тесту. |
| `createdAt`      | Час UTC, коли подію зафіксовано, а не час її доставки.                                                                     |
| `data`           | Незмінний знімок ресурсу на момент фіксації.                                                                               |

Суми є цілими числами в найменших одиницях валюти відповідного поля. Наприклад, `10000` із числовим ID валюти ISO 4217 `203` означає 100,00 CZK. Запитані суми та суми розрахунку можуть бути в різних валютах.

Кожен тип події містить у `data` власний знімок. Усі структури payload і значення статусів наведено в розділі [Типи подій](/webhooks/events).

## Правила доставки [#delivery-rules]

Tapaya надсилає подію, щойно її зміну збережено, і надсилає її повторно, доки ваш сервер не відповість `2xx`.

| Правило         | Поведінка                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| Підтвердження   | Будь-яка відповідь `2xx` протягом 10 секунд. Переспрямування не виконуються.                                       |
| Повторні спроби | Щонайбільше 12 спроб протягом приблизно 20 годин з очікуванням 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 і 360 хвилин. |
| Порядок         | Не гарантовано. Доставка відбувається принаймні один раз, тому очікуйте дублікати та старіші знімки.               |
| Одночасність    | 2 запити одночасно на організацію, спільно з ручними тестами. Інші події очікують у черзі.                         |

Невдала доставка ніколи не змінює сам платіж, а минулі доставки неможливо надіслати повторно. Щоб надолужити пропущене після збою, зчитайте поточний стан через [API платежів і мерчантів](/platform-api/reporting).

## Почніть інтеграцію [#start-integrating]

<Cards>
  <Card title="Налаштуйте цільову адресу" href="/webhooks/configuration">
    Задайте URL, виберіть події та збережіть signing secret (ключ підпису).
  </Card>

  <Card title="Перегляньте типи подій" href="/webhooks/events">
    Знайдіть точну умову надсилання кожної події платежу, мерчанта та онбордингу.
  </Card>

  <Card title="Перевірте й протестуйте" href="/webhooks/receiving">
    Перевірте підписи та надішліть діагностичний вебхук.
  </Card>
</Cards>