Джерела

Джерело — це один підключений сторонній сервіс, наприклад Stripe чи GitHub, разом із тим, що потрібно Railhook, щоб переконатися: вебхук справді надіслав саме він. Створивши джерело, ви отримуєте ingress-адресу, яку вставляєте в налаштування провайдера.

Як це працює

1. Провайдер надсилає вебхук на ingress-адресу джерела.

2. Railhook перевіряє його так, як налаштовано джерело. Вебхук, що не пройшов перевірку, Railhook відхиляє й не зберігає.

3. Railhook зберігає вебхук таким, яким той надійшов, як вхідну подію. У панелі такі події зібрано в розділі «Отримані».

4. Railhook створює по одному пересиланню на кожне призначення джерела і доставляє кожне, доки воно не вдасться або Railhook його не полишить. Див. Призначення.

Створення джерела

Node.js

import { Railhook } from '@railhook/node';

const client = new Railhook({ apiKey: process.env.RAILHOOK_API_KEY, baseUrl: process.env.RAILHOOK_URL });

const source = await client.incomingSources.create(projectId, {
  name: 'Stripe',
  providerType: 'STRIPE',
  verificationMode: 'PROVIDER',
  hmacSecret: process.env.STRIPE_WEBHOOK_SECRET,
});

console.log(source.ingressUrl);

Python

import os

from railhook import IncomingSourceCreateParams, Railhook

client = Railhook(api_key=os.environ["RAILHOOK_API_KEY"], base_url=os.environ["RAILHOOK_URL"])

source = client.incoming_sources.create(
    project_id,
    IncomingSourceCreateParams(
        name="Stripe",
        provider_type="STRIPE",
        verification_mode="PROVIDER",
        hmac_secret=os.environ["STRIPE_WEBHOOK_SECRET"],
    ),
)

print(source.ingress_url)

PHP

<?php
use Railhook\Railhook;

$client = new Railhook(apiKey: getenv('RAILHOOK_API_KEY'), baseUrl: getenv('RAILHOOK_URL'));

$source = $client->incomingSources->create($projectId, [
    'name' => 'Stripe',
    'providerType' => 'STRIPE',
    'verificationMode' => 'PROVIDER',
    'hmacSecret' => getenv('STRIPE_WEBHOOK_SECRET'),
]);

echo $source['ingressUrl'];

cURL

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":"Stripe","providerType":"STRIPE","verificationMode":"PROVIDER","hmacSecret":"'"$STRIPE_WEBHOOK_SECRET"'"}'

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

Поле	Що робить
name	Обов’язкове. Назва, яку видно в панелі, до 255 символів.
slug	Назва для URL: малі латинські літери, цифри й дефіси, до 64 символів. Якщо не вказати, Railhook згенерує її сам.
providerType	GENERIC, GITHUB, GITLAB, STRIPE, SHOPIFY, SLACK або TWILIO.
verificationMode	NONE, HMAC_GENERIC або PROVIDER. Якщо не вказати, залежить від hmacSecret: із секретом — PROVIDER для провайдера з готовим пресетом і HMAC_GENERIC для GENERIC; без секрету — NONE. Див. Перевірка вхідних вебхуків.
hmacSecret	Секрет, яким провайдер підписує вебхуки. Лише для запису: API ніколи його не повертає.
hmacHeaderName, hmacSignaturePrefix	Де шукати підпис у режимі HMAC_GENERIC.
rateLimitPerSecond	Скільки запитів за секунду приймає це джерело.
status	ACTIVE або DISABLED.

Ingress-адреса

Ingress-адреса складається з WEBHOOK_INGRESS_BASE_URL, шляху /ingress/ і непрозорого токена. Джерело визначає лише цей токен, тож бережіть адресу, як облікові дані. А не дає тому, хто її дізнався, надсилати вам події саме перевірка.

Обережно

Укажіть у WEBHOOK_INGRESS_BASE_URL публічну адресу, до якої звертаються провайдери. З неї Railhook складає адресу на сторінці джерела, і саме цю адресу, символ у символ, підписує Twilio.

Що відповідає ingress

Кожен код бачить механізм повторних спроб провайдера.

Статус	Значення
200	Запит-підтвердження Slack url_verification до джерела SLACK: коли підпис перевірено, Railhook відповідає {"challenge":"…"}. Так Slack вмикає Request URL, тож джерелу потрібна перевірка PROVIDER із секретом підпису (Signing Secret) застосунку. Підтвердження — не подія: Railhook нічого не зберігає, не пересилає й не рахує.
202	Прийнято й збережено. У тілі — requestId.
401	Перевірку налаштовано, а підпис не збігся, або вже бачений підпис прийшов із вебхуком, який не є повторним надсиланням уже збереженого. Нічого не збережено.
403	Організацію призупинено. Railhook відповідає 403, а не 410, щоб провайдер, який на 410 видаляє підписку, зберіг її до того, як призупинення знімуть.
404	Джерела з таким токеном немає або його проєкт видалено.
410	Джерело існує, але вимкнене.
413	Тіло перевищує ліміт, типово 512 КБ.
429	Вичерпано ліміт запитів джерела, з Retry-After: 1. Railhook відповідає так само, але з Retry-After: 3600, коли організація зараз не може приймати нові вебхуки; на повторне надсилання вже збереженого вебхука все одно приходить 202.

Змінна	Типово	Дія
WEBHOOK_INCOMING_MAX_PAYLOAD_SIZE_BYTES	524288	Максимальний розмір тіла, який приймає ingress.
WEBHOOK_INCOMING_RATE_LIMIT_PER_SECOND	100	Ліміт запитів для джерела, яке не задало власного. 0 вимикає цей типовий ліміт.

Повторні надсилання від провайдера

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

Провайдер	Ідентифікатор
Загальний	заголовок X-Webhook-Id
Stripe	id у JSON-тілі (evt_…), у запиті, підписаному Stripe-Signature
GitHub	заголовок X-GitHub-Delivery
GitLab	заголовок webhook-id або Idempotency-Key (GitLab 17.4 і новіші)
Shopify	заголовок X-Shopify-Webhook-Id
Twilio	заголовок I-Twilio-Idempotency-Token
Slack	event_id у JSON-тілі

Вебхуки від провайдера, який не надсилає жодного з них, не дедуплікуються.