Безпека ендпоінта

Ротація секрету підпису

Викличте POST /api/v1/projects/{projectId}/endpoints/{id}/rotate-secret або виконайте ротацію в панелі. Відповідь містить новий secret і standardWebhooksSecret.
Протягом перехідного періоду ендпоінта (типово 24 години) кожна доставка має два підписи: один зроблено новим секретом, другий старим. Отримувач пройде перевірку з будь-яким із них.
За цей час розгорніть новий секрет в отримувача. Коли період мине, старим секретом більше нічого не підписуватимуть, і отримувач, який досі його використовує, не пройде перевірку.

Офіційні SDK протягом перехідного періоду приймають будь-який із двох підписів. Як виглядають заголовки, див. у розділі Перевірка підписів.

Доведіть, що ендпоінт ваш

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

`WEBHOOK_ENDPOINT_VERIFICATION_REQUIRED`	Новий ендпоінт починає зі статусу
`false` (типово)	`SKIPPED` і одразу отримує доставки.
`true`	`PENDING` і нічого не отримує, доки його не перевірять або перевірку не пропустять.

Доставки йдуть лише на ендпоінт зі статусом VERIFIED або SKIPPED. Доставка на будь-який інший ендпоінт завершується невдачею без повторних спроб. Зміна URL так само скидає статус ендпоінта, тож перевірений ендпоінт не вийде перенаправити на іншу адресу й далі отримувати доставки.

Викличте POST /api/v1/projects/{projectId}/endpoints/{id}/verify. Railhook надсилає на URL ендпоінта такий запит і чекає до 10 секунд:
Що надсилає Railhook
```
POST /webhooks HTTP/1.1
Content-Type: application/json

{"type":"webhook.verification","challenge":"<token>","timestamp":"2026-09-13T10:30:00Z"}
```
Відповідайте значенням challenge у JSON або просто токеном:
Що відповісти
```
HTTP/1.1 200 OK
Content-Type: application/json

{"challenge":"<token>"}
```
Якщо відповідь збігається, ендпоінт отримує статус VERIFIED. За будь-якої іншої відповіді статус FAILED, і перевірку можна запустити знову.

Щоб доставляти без перевірки, викличте POST /api/v1/projects/{projectId}/endpoints/{id}/skip-verification із полем reason. Причина зберігається в ендпоінті, тож неперевірений ендпоінт залишається зафіксованим рішенням, а не крок, який непомітно пропустили.

Клієнтський сертифікат (mTLS)

Якщо ендпоінт вимагає, щоб Railhook підтвердив свою особу на рівні TLS, налаштуйте клієнтський сертифікат через POST /api/v1/projects/{projectId}/endpoints/{id}/mtls:

Поле
`clientCert`	Обов’язкове. PEM. Пред’являється під час кожної доставки на цей ендпоінт.
`clientKey`	Обов’язкове. PEM, що відповідає сертифікату.
`caCert`	Необов’язкове. PEM. Потрібне, коли сертифікат ендпоінта підписано центром сертифікації, якого немає у сховищі довірених сертифікатів платформи, наприклад внутрішнім CA.

Після цього ендпоінт повертає mtlsEnabled: true; сам сертифікат і ключ API не повертає. Видалити їх можна запитом DELETE на той самий шлях.

Куди можуть іти доставки

Кожен URL ендпоінта перевіряється під час збереження й ще раз перед кожною спробою. Адреси loopback, link-local і приватні діапазони Railhook відхиляє, якщо оператор їх не дозволив. Це налаштування всього розгортання, а не окремого ендпоінта, бо таке рішення ухвалює оператор, а не організація.

Змінна	Типово	Дія
`WEBHOOK_ALLOW_PRIVATE_IPS`	`false`	`true` дозволяє всі приватні адреси. Якщо `APP_ENV=production`, застосунок із таким значенням не запуститься.
`WEBHOOK_ALLOWED_HOSTS`	порожньо	Імена хостів через кому, для яких перевірка не діє; порівнюються так, як їх записано в URL. Це підтримуваний спосіб звертатися до окремого внутрішнього сервісу.

Та сама перевірка діє для вхідних призначень і для HTTP-кроків у воркфлоу.

Обмеження навантаження на ендпоінт

Налаштування	Дія
`rateLimitPerSecond` в ендпоінті	Скільки доставок за секунду може піти на цей ендпоінт, від 0 до 10 000. `0` знімає ліміт.
`WEBHOOK_MAX_CONCURRENT_PER_ENDPOINT`	Скільки спроб одночасно може виконуватися на один ендпоінт, типово `5`.

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

Дозволені IP-адреси джерела

Як зберігаються секрети

Секрети підпису, клієнтські сертифікати й клієнтські ключі ендпоінтів зберігаються зашифрованими ключем шифрування розгортання. caCert публічний, тож зберігається як є. Ключ шифрування оператор задає через WEBHOOK_ENCRYPTION_KEY або версіонованими ключами в WEBHOOK_ENCRYPTION_KEYS і WEBHOOK_ENCRYPTION_KEY_ACTIVE_VERSION. Див. Конфігурація.