# Налаштування (/uk/webhooks/configuration)





Кожна організація має одну цільову адресу вебхуків і один активний signing secret (ключ підпису). Налаштуйте їх у Platform або зі свого сервера.

| Відомості           | Значення                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| Базовий URL         | `https://api.sandbox.tapaya.com` для пісочниці (sandbox), `https://api.tapaya.com` для робочого середовища |
| Автентифікація      | Server Secret Token у заголовку `Authorization`. Див. [Автентифікація](/platform-api#authentication).      |
| Область дії         | Одна цільова адреса на організацію                                                                         |
| Пов'язаний посібник | [Перевірка й тестування](/webhooks/receiving)                                                              |

## Налаштуйте вебхуки в Platform [#configure-in-the-platform]

Відкрийте [API Keys](https://platform.tapaya.com/api-keys/) для своєї організації і знайдіть **Webhooks**.

1. Введіть свою публічну HTTPS URL-адресу.
2. Виберіть потрібні події або ввімкніть **Subscribe to all webhook types**.
3. Увімкніть **Enable** і натисніть **Save**.
4. Скопіюйте signing secret і збережіть його на своєму сервері.
5. Надішліть [тестовий вебхук](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="Signing secret показується лише один раз">
  Скопіюйте його, коли створюєте цільову адресу або виконуєте ротацію; пізніше його неможливо отримати. Він лише перевіряє вхідні вебхуки. Ваш Server Secret Token авторизує запити налаштування.
</Callout>

## Усі операції [#all-operations]

| Операція                                           | Використовуйте, щоб                                                  |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| [Збереження цільової адреси](#save-a-destination)  | Створення або заміна поточної підписки чи ротація її signing secret. |
| [Отримання цільової адреси](#read-a-destination)   | Отримання поточної URL-адреси, режиму підписки та стану ввімкнення.  |
| [Видалення цільової адреси](#delete-a-destination) | Видалення підписки та її черги й історії доставок.                   |

## Керування цільовою адресою [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Збережіть цільову адресу" id="save-a-destination">
    **Використовуйте, щоб** підключити свій HTTPS-обробник і вибрати події для доставки.

    ```bash
    curl --request PUT \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME' \
      --header 'Content-Type: application/json' \
      --data '{
        "url": "https://payments.example.com/webhooks/tapaya",
        "eventTypes": ["payment.succeeded", "payment.failed", "payment.refund.succeeded"],
        "subscribeAllEventTypes": false,
        "enabled": true,
        "rotateSecret": false
      }'
    ```

    **Варто знати:**

    * Ця операція замінює збережені налаштування; вона не додає другий ендпоінт.
    * Створення та явна ротація повертають `{"signingSecret":"twhsec_..."}`. Звичайне оновлення повертає `{"signingSecret":null}`.
    * Збережіть повний повернений ключ, включно з префіксом. GET ніколи його не повертає.
    * Організацію визначає ваш токен; не надсилайте ID організації.

    **Параметри:**

    | Поле                     | Обов'язкове | Значення                                                                                                                   |
    | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `url`                    | Так         | Публічна HTTPS URL-адреса на порту 443, до 2 048 символів, без вбудованих облікових даних або фрагмента.                   |
    | `eventTypes`             | Так         | Масив назв із [каталогу](/webhooks/events). Виберіть принаймні одну, якщо не підписуєтеся на всі типи.                     |
    | `subscribeAllEventTypes` | Ні          | Типове значення `false`. Задайте `true` разом із `eventTypes: []`, щоб включити всі поточні та майбутні підтримувані типи. |
    | `enabled`                | Так         | За значення `true` фіксує нові відповідні події та надсилає події з черги.                                                 |
    | `rotateSecret`           | Так         | За значення `true` генерує та повертає новий signing secret.                                                               |
  </Accordion>

  <Accordion title="Отримайте цільову адресу" id="read-a-destination">
    **Використовуйте, щоб** переглянути збережену підписку, не розкриваючи її signing secret.

    ```bash
    curl 'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Варто знати:**

    * GET повертає `404`, якщо ця організація не має цільової адреси.
    * Підписки на всі типи повертають порожній масив `eventTypes` із `subscribeAllEventTypes: true`.
    * Відповідь ніколи не містить signing secret.
    * Використовуйте `availableEventTypes`, щоб створити вибір подій без жорстко закодованого каталогу.

    **Повертає:**

    | Поле                     | Значення                                              |
    | ------------------------ | ----------------------------------------------------- |
    | `url`                    | Збережена цільова HTTPS-адреса.                       |
    | `eventTypes`             | Явні підписки або порожній масив у режимі всіх типів. |
    | `subscribeAllEventTypes` | Чи вибрані поточні та майбутні підтримувані типи.     |
    | `enabled`                | Чи ввімкнені вебхуки.                                 |
    | `availableEventTypes`    | Усі назви подій, на які можна підписатися.            |
  </Accordion>

  <Accordion title="Видаліть цільову адресу" id="delete-a-destination">
    **Використовуйте, щоб** відключити організацію та видалити її доставки в черзі й історію доставок.

    ```bash
    curl --request DELETE \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Варто знати:**

    * Успіх повертає HTTP `204` без тіла відповіді.
    * Запит, який уже надсилається, може надійти й після видалення.
    * Повторне створення цільової адреси генерує новий signing secret і не відновлює видалені події.
  </Accordion>
</Accordions>

## Правила цільової адреси [#configuration]

### Зміна налаштувань [#configuration-changes]

| Коли ви                             | Що відбувається                                                                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Змінюєте URL-адресу, події або ключ | Нові події використовують нові налаштування. Події в черзі зберігають стару URL-адресу та ключ, тому підтримуйте обидва робочими, доки черга не спорожніє.                     |
| Вимикаєте вебхуки                   | Доставки з черги призупиняються, нові події не фіксуються. Повторне ввімкнення відновлює обробку черги, але пропущені зміни не додаються заднім числом. Тести й далі працюють. |
| Видаляєте цільову адресу            | Події в черзі та історія доставок видаляються. Запит, який уже надсилається, усе ще може надійти. Повторне створення генерує новий signing secret.                             |

### Вимоги до URL-адреси [#destination-requirements]

* Публічний HTTPS на порту 443. Localhost і приватні мережі відхиляються, а DNS повторно перевіряється під час кожного підключення.
* Без вбудованих облікових даних, без фрагмента та без переспрямувань.
* Без власних заголовків авторизації. Натомість перевіряйте підпис Tapaya або розмістіть серверний адаптер перед URL-адресою, що вимагає власного ключа.

## Помилки [#errors]

Запити налаштувань завершуються помилкою з такими відповідями. Обробник, який відхиляє або пропускає доставку, є іншою проблемою; див. [Обробка помилок](/webhooks/receiving#handle-errors).

| Відповідь     | Значення                                                                                                  |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `400` для PUT | Недійсна URL-адреса, непідтримуваний тип події, відсутнє обов'язкове поле або порожній явний вибір подій. |
| `401`         | Server Secret Token відсутній або недійсний.                                                              |
| `404` для GET | Для автентифікованої організації немає цільової адреси.                                                   |

Продовжуйте з [перевіркою підпису та тестовою доставкою](/webhooks/receiving).