> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.erlcrussia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Вебхук Подій

Щоб отримувати вебхуки з гри:

1. Введіть `/вебхук управління` на нашому Discord-сервері.
2. У меню, що з'явилося, вкажіть URL вашого **кастомного** вебхука. 
3. Перш ніж натискати кнопку «Додати», обов'язково натисніть кнопку «Перевірити».
   * Система надішле тестове повідомлення. Якщо воно надійшло — значить, усе налаштовано вірно і вебхук можна сміливо пускати в роботу.
4. Після успішної перевірки натисніть кнопку «Додати», щоб активувати отримання даних.

<Danger>
  **Ми НЕ підтримуємо прямі вебхуки Discord. Система працює виключно з кастомними вебхуками (вашими власними обробниками).**
</Danger>

Ваш ендпоінт зобов'язаний перевіряти Ed25519 підписи на кожному запиті. Гра збереже лише ті URL, які пройдуть перевірку.

***

### Вимоги

#### Ваш ендпоінт повинен приймати

* `POST` запити з JSON тілом.
* Ці заголовки на кожному підписаному запиті:
  * `X-Signature-Ed25519` (hex-кодований Ed25519 підпис).
  * `X-Signature-Timestamp` (рядок Unix timestamp).

#### Ваш Ендпоінт Повинен:

1. Прочитати **сирі байти тіла запиту** точно в тому вигляді, в якому вони отримані (не серіалізуйте JSON наново).
2. Прочитати `X-Signature-Timestamp`.
3. Прочитати `X-Signature-Ed25519`.
4. Перевірити підпис для:

   `message = timestamp + raw_body`

   Де `timestamp` — це значення заголовка у вигляді рядка, об'єднане напряму з сирими байтами тіла.
5. Повернути:
   * **2xx** тільки якщо підпис вірний.
   * **4xx** якщо заголовки відсутні, невірні або перевірка підпису не вдалася.

***

### Публічний Ключ

Використовуйте цей Ed25519 публічний ключ (base64, SubjectPublicKeyInfo / SPKI):

```
MCowBQYDK2VwAyEArbRTkyh3A035YUWWZdyF3vck4QN3I7uU8cp7YaxocFE=
```

***

### Деталі Реалізації

#### Вхідні Дані

* `timestamp`: точний рядок із `X-Signature-Timestamp`.
* `sigHex`: точний рядок із `X-Signature-Ed25519` (hex).
* `rawBody`: сирі байти тіла запиту.

#### Кроки

1. Декодуйте `sigHex` з hex у байти.
2. Побудуйте `message` як:
   * Байти `timestamp` в UTF-8
   * Одразу слідом `rawBody`
3. Перевірте Ed25519 підпис за допомогою публічного ключа вище.

#### Поширені Помилки

* Не використовуйте розпарсений JSON об'єкт для перевірки. Використовуйте лише сирі байти тіла.
* Не додавайте роздільники або пробіли між timestamp та тілом.
* Обробляйте підпис як hex, а не base64.
* Переконайтеся, що ваш фреймворк не поглинає тіло до того, як ви його захопите.

***

### Які події надсилаються?

Наразі гра надсилає вебхуки для:

* Повідомлень, що починаються з **;**
  * Це дозволяє створювати власні внутрішньоігрові команди!
* Emergency Calls (Екстрені Виклики)

У майбутньому можуть бути додані нові події. Зверніть увагу: система вебхуків не призначена для заміни опитування HTTP API або WebSocket.