Перейти до вмісту
NimbusNexus

Верифікація ендпоінтів

Верифікація доводить, що URL за ендпоінтом належить вам і готовий приймати вебхуки. Ми надсилаємо на нього один підписаний challenge; ендпоінт проходить верифікацію, повернувши challenge у відповіді. Доки він її не пройде, робочий простір, що вимагає верифікації, нічого на нього не доставляє, — так можна виявити URL з помилкою чи недобудованого отримувача, перш ніж справжні події накопичаться в dead-letter черзі, і ніхто не зможе націлити наші доставки на сервер, який їх ніколи не просив.

Challenge-запит

Запуск верифікації надсилає один POST-запит на URL ендпоінта, підписаний секретом ендпоінта точно так само, як доставка (ті самі X-Webhook-Signature і X-Webhook-Timestamp, користувацькі заголовки вашого ендпоінта та X-Webhook-Event-Type: webhook.verify):

JSON
{"type": "webhook.verify", "data": {"endpoint_id": "ep_3f9a…", "challenge": "Xb9kQ2…"}}

Ендпоінт проходить верифікацію, коли відповідає 2xx зі значенням challenge будь-де в тілі відповіді. Відповідь 2xx без токена провалюється з challenge_not_echoed; будь-що інше провалюється так само, як провалилася б доставка.

Як на нього відповісти

Перевірте підпис, як для кожної доставки, а потім поверніть challenge:

event = json.loads(raw_body)                       # after the signature check
if event["type"] == "webhook.verify":
    return Response(event["data"]["challenge"], status=200)

No REST example here; showing Python.

Запуск

У консолі відкрийте меню ендпоінта на сторінці Endpoints і виберіть Verify. Через API:

Shell
curl -sX POST https://webhooks.nimbusnexus.net/v1/endpoints/ep_3f9a…/verify \
  -H "Authorization: Bearer $ADMIN_KEY"
JSON
{ "verified": true, "challenge_echoed": true, "status_code": 200, "error": null, "duration_ms": 142, "failure_reason": null }

Ендпоінт лишається верифікованим, доки не зміниться його URL; новий URL має пройти верифікацію знову.

Коли вона обовʼязкова

Верифікація обовʼязкова для ендпоінта, коли ввімкнено будь-що з цього:

  • перемикач робочого простору — Settings → Endpoint verification у консолі або PATCH /v1/workspace з {"require_endpoint_verification": true};
  • перемикач проєкту — PUT /v1/verification-policy?project_id=… з {"required": true}, для проєкту, якому вона потрібна, коли іншим — ні;
  • ваш план, якщо план цього вимагає. Тоді консоль показує перемикач заблокованим у ввімкненому стані.

GET /v1/verification-policy повертає правило в тому вигляді, у якому його застосовує доставка (required), разом з обома перемикачами.

Що пропускає неверифікований ендпоінт

Коли верифікація обовʼязкова, неверифікований ендпоінт пропускається під час розгалуження події: відповідь на публікацію враховує його в skipped_unverified, консоль позначає ендпоінт як gated, і жодної доставки для нього не створюється, тож після верифікації ніщо не чекає на надсилання. Після того як ендпоінт пройде верифікацію, опублікуйте або переграйте подію знову.

Повторне надсилання блокується так само. Спроба повторно доставити одну доставку на цей ендпоінт або переграти на нього подію відхиляється з 409 endpoint_not_verified; масова повторна доставка чи реплей за проміжок часу пропускає ендпоінт і враховує його в skipped_unverified. Доставка, яка вже стоїть у черзі чи повторюється, коли ендпоінту стає потрібна верифікація, — вимогу ввімкнули або URL ендпоінта змінився, — потрапляє в dead-letter чергу ненадісланою, з last_error, що починається з «not verified:». Верифікуйте ендпоінт, а потім повторно доставте її.

Отримувачі, які не можуть відповісти

Деякі отримувачі приймають будь-який POST, але ніколи не повертають тіло, яке ви обираєте, — серед них вхідні вебхуки Slack і catch hooks Zapier. Вони не можуть пройти верифікацію. Якщо ваш план дозволяє, лишіть верифікацію вимкненою для проєкту, який на них доставляє; інакше поставте перед ними невеликий власний ретранслятор, що відповідає на challenge.

Що далі

Edit this page on GitHub