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

Перевірка вхідних вебхуків

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

Режими перевірки

Section titled “Режими перевірки”
verificationMode Що перевіряється
NONE Нічого. Усе, що надійшло на адресу, зберігається й пересилається. Використовуйте лише під час підключення провайдера.
PROVIDER Власна схема провайдера, обрана за providerType. Її має кожен тип провайдера, окрім GENERIC.
HMAC_GENERIC Підпис HMAC-SHA256 у заголовку, який ви вказуєте. Саме так перевіряється провайдер GENERIC.

На запит, що не пройшов перевірку, відповідь — 401, і він не зберігається.

Провайдери

Section titled “Провайдери”
providerType Заголовок Як перевіряється
GITHUB X-Hub-Signature-256 sha256=, а за ним hex HMAC-SHA256 від сирого тіла.
GITLAB X-Gitlab-Token Заголовок має дорівнювати секрету. GitLab надсилає токен, а не підпис.
STRIPE Stripe-Signature t=…,v1=…: hex HMAC-SHA256 від <t>.<сире тіло>. t має відрізнятися від поточного часу не більш ніж на 300 секунд.
SHOPIFY X-Shopify-Hmac-SHA256 Base64 HMAC-SHA256 від сирого тіла.
SLACK X-Slack-Signature, X-Slack-Request-Timestamp v0=, а за ним hex HMAC-SHA256 від v0:<timestamp>:<сире тіло>. Мітка часу має відрізнятися від поточного часу не більш ніж на 300 секунд.
TWILIO X-Twilio-Signature Base64 HMAC-SHA1 з auth token. Для запитів у form-encoded він покриває URL, за яким ідуть усі параметри, відсортовані за назвою; для інших запитів — URL, а параметр запиту bodySHA256 має відповідати тілу.

Для кожного провайдера секрет задається в hmacSecret джерела: секрет підпису вебхуків, секретний токен GitLab або auth token Twilio.

Налаштування провайдера

Section titled “Налаштування провайдера”

  1. Створіть джерело з verificationMode зі значенням PROVIDER, providerType і секретом провайдера:

    Terminal window
    curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/incoming-sources" \
      -H "X-API-Key: $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"GitHub","providerType":"GITHUB","verificationMode":"PROVIDER","hmacSecret":"'"$GITHUB_WEBHOOK_SECRET"'"}'

  2. Вставте ingressUrl джерела в налаштування вебхуків провайдера з тим самим секретом.

  3. Надішліть тестовий вебхук від провайдера. Він з’явиться в розділі «Отримані»; на підпис, що не збігся, відповідь — 401, і вебхук там не з’явиться.

Загальний HMAC

Section titled “Загальний HMAC”

Для провайдера без пресету використовуйте HMAC_GENERIC:

Поле Типово Значення
hmacHeaderName X-Signature Заголовок, що несе підпис.
hmacSignaturePrefix немає Префікс, який відкидається перед порівнянням, наприклад sha256=.
hmacSecret Спільний секрет.

Приймаються дві форми заголовка:

Форма Що підписано Захист від повторів
t=<unix-ms>,v1=<hex>, власний формат Railhook <t>.<сире тіло> t має відрізнятися від поточного часу не більш ніж на 300 секунд.
Сам hex-хеш Лише сире тіло Підпис не захищає: той самий запит проходить перевірку, доки живе секрет.
Terminal window
curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/incoming-sources" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme","providerType":"GENERIC","verificationMode":"HMAC_GENERIC","hmacHeaderName":"X-Acme-Signature","hmacSignaturePrefix":"sha256=","hmacSecret":"'"$ACME_SECRET"'"}'

Повторно використані підписи

Section titled “Повторно використані підписи”

Перевірений підпис запам’ятовується на певне вікно, і другий запит із тим самим підписом у цьому вікні відхиляється з 401. Для провайдерів, чий підпис містить мітку часу, це прибирає дублікати. Для самого hex-хеша це єдиний захист від того, що перехоплений запит надішлють знову.

Змінна Типово
WEBHOOK_INGRESS_REPLAY_WINDOW_MINUTES 5

Що далі

Section titled “Що далі”
ДжерелаСтворіть джерело й дізнайтеся, що відповідає ingress.
ПризначенняПересилайте перевірені вебхуки у ваші сервіси.
Перевірка підписівІнший напрямок: як отримувачі перевіряють Railhook.