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

Усе на ендпоінті, що стосується довіри: його секрет для підпису, доказ того, що той, хто його зареєстрував, ним володіє, сертифікат, який Railhook йому пред’являє, і мережеві правила, через які проходить кожна доставка.

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

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

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

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

URL, який може ввести будь-хто, — це 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; сертифікат і ключ не повертаються. Приберіть їх запитом DELETE на той самий шлях.

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

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

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

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

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

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

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

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

Секрети у сховищі

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

Що далі

Перевірка підписівПеревіряйте підпис кожної доставки.

Статична вихідна IP-адресаДайте отримувачам одну адресу для білого списку.

КонфігураціяУсі налаштування розгортання, зокрема наведені вище.