Призначення

Призначення — це ваша URL-адреса, на яку надходять вебхуки джерела, разом зі способом автентифікації на ній. Для кожної вхідної події Railhook створює по одному пересиланню на кожне увімкнене призначення її джерела. У кожного призначення власні повторні спроби, тайм-аут і облікові дані, тож повільний сервіс не затримує решту.

Додавання призначення

const destination = await client.incomingSources.createDestination(projectId, sourceId, {
  url: 'https://billing.internal.example.com/webhooks/stripe',
  enabled: true,
  maxAttempts: 5,
  timeoutSeconds: 30,
});

from railhook import IncomingDestinationCreateParams

destination = client.incoming_sources.create_destination(
    project_id,
    source_id,
    IncomingDestinationCreateParams(
        url="https://billing.internal.example.com/webhooks/stripe",
        enabled=True,
        max_attempts=5,
        timeout_seconds=30,
    ),
)

<?php
$destination = $client->incomingSources->createDestination($projectId, $sourceId, [
    'url' => 'https://billing.internal.example.com/webhooks/stripe',
    'enabled' => true,
    'maxAttempts' => 5,
    'timeoutSeconds' => 30,
]);

curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/incoming-sources/$SOURCE_ID/destinations" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://billing.internal.example.com/webhooks/stripe",
    "authType": "BEARER",
    "authConfig": "{\"token\":\"'"$BILLING_TOKEN"'\"}",
    "timeoutSeconds": 30
  }'

Поле	Що робить
`url`	Обов’язкове. Куди Railhook надсилає пересилання. Як і URL ендпоінта, перевіряється на належність до приватних діапазонів адрес, див. Безпека ендпоінта.
`enabled`	Чи отримує призначення пересилання.
`authType`, `authConfig`	Як Railhook автентифікується, див. нижче. `authConfig` — JSON-рядок до 4096 символів, який зберігається в зашифрованому вигляді.
`customHeadersJson`	Додаткові HTTP-заголовки як JSON-об’єкт у рядку.
`maxAttempts`	Скільки спроб Railhook зробить, перш ніж полишити пересилання. Типово `5`.
`retryDelays`	Інтервали між спробами в секундах, через кому. Типово `60,300,900,3600,21600`.
`retryableStatuses`	Які HTTP-статуси варті ще однієї спроби. Типово `408,429,500-599`. Див. Які статуси варті повтору.
`autoDisabledAt`	Лише для читання. Проставляється, коли Railhook вимкнув це призначення після цілого вікна суцільних невдач. Див. Коли Railhook вимикає ендпоінт; призначення вимикається на тих самих умовах.
`timeoutSeconds`	Скільки одна спроба чекає на відповідь. Типово `30`.
`transformationId`	Збережена трансформація, яку Railhook застосовує перед пересиланням.
`payloadTransform`	Вираз JSONPath, наприклад `$.data`; діє, коли `transformationId` не задано.

Автентифікація

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

`authType`	`authConfig`	Як надсилається
`NONE`	немає	Нічого.
`BEARER`	`{"token": "…"}`	`Authorization: Bearer <token>`
`BASIC`	`{"username": "…", "password": "…"}`	`Authorization: Basic <base64>`
`CUSTOM_HEADER`	`{"headerName": "…", "headerValue": "…"}`	Заголовок із вказаною назвою

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

Що отримує призначення

Якщо трансформацію не налаштовано, тіло — це вебхук точно в тому вигляді, в якому його надіслав провайдер, байт у байт, з оригінальним Content-Type і, якщо він був, Content-Encoding. Трансформоване тіло надсилається в UTF-8. Railhook додає такі заголовки:

Заголовок	Значення
`X-Incoming-Event-Id`	Вхідна подія.
`X-Incoming-Request-Id`	Ідентифікатор запиту, який ingress повернув провайдеру.
`X-Forward-Attempt`	Номер спроби, починаючи з 1.
`Idempotency-Key`	`<incoming event id>-<destination id>`, однаковий для всіх спроб.

Із власних заголовків провайдера Railhook передає лише ті, що описують подію, з трансформацією чи без, бо деякі провайдери ніде більше не вказують, що це за подія: push і issue від GitHub за тілом не розрізнити.

Провайдер	Заголовки, що передаються
GitHub	`X-GitHub-Event`, `X-GitHub-Delivery`, `X-GitHub-Hook-ID`, `X-GitHub-Hook-Installation-Target-Type`, `X-GitHub-Hook-Installation-Target-ID`
GitLab	`X-Gitlab-Event`, `X-Gitlab-Event-UUID`, `X-Gitlab-Instance`
Shopify	`X-Shopify-Topic`, `X-Shopify-Webhook-Id`, `X-Shopify-Shop-Domain`, `X-Shopify-API-Version`, `X-Shopify-Event-Id`, `X-Shopify-Triggered-At`

Якщо заголовок із такою самою назвою задає Railhook, облікові дані призначення чи його власні заголовки, перевагу має саме він. Решту оригінальних заголовків Railhook не пересилає, а підписи й токени не пересилає ніколи (X-Hub-Signature-256, X-Shopify-Hmac-Sha256, X-Gitlab-Token, Stripe-Signature тощо). Перевірка вже відбулася на ingress; ваш сервіс натомість має покладатися на облікові дані призначення.

Трансформація перед пересиланням

Railhook бере перше, що задано: збережену трансформацію transformationId, потім вираз JSONPath payloadTransform, інакше — тіло без змін. Якщо налаштовану трансформацію не вдалося застосувати, спроба вважається невдалою, і Railhook повторить її; нетрансформоване тіло замість трансформованого ніколи не пересилається. Див. Трансформації.

Коли призначення не відповідає

Пересилання йдуть за розкладом повторних спроб вхідного напрямку: 5 спроб з інтервалами 1 хв, 5 хв, 15 хв і 1 год і випадковим розкидом від 50% до 150%. Після 408, 429, будь-якого 5xx, помилки з’єднання, тайм-ауту чи хоста призначення, якого не вдалося знайти в DNS, Railhook повторює спробу; будь-який інший 4xx або 3xx одразу переносить пересилання в «Недоставлені пересилання», без решти розкладу, бо ця відповідь не зміниться, доки хтось не виправить призначення. Переспрямувань Railhook не виконує. Пересилання, яке не завершилося через 24 години після початку, Railhook полишає незалежно від кількості спроб. Повторна спроба з «Недоставлених повідомлень» або відтворення запускає нове пересилання, тож його 24 години рахують від повторної спроби чи відтворення, а не від надходження вебхука.

Полишені пересилання потрапляють у розділ «Недоставлені пересилання». Повторна спроба створює нове пересилання на те саме призначення, яке знову починає зі спроби 1. Див. Повторні спроби та недоставлені повідомлення.