Ендпоінти та підписки

Ендпоінт є URL, який приймає ваші події. Підписка визначає, які типи подій він отримує. На кожну надіслану подію Railhook створює по одній доставці на кожен ендпоінт із відповідною підпискою.

Екран «З’єднання» в панелі показує ендпоінт із його підписками як одне з’єднання. Це лише спосіб показу, а не окремий запис.

У прикладах $RAILHOOK_URL означає ваш API Railhook, $PROJECT_ID ваш проєкт, а $API_KEY API-ключ проєкту.

Як створити ендпоінт і підписати його

1. Створіть ендпоінт.

   curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/endpoints" \
     -H "X-API-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://api.customer.com/webhooks","description":"Orders"}'

   Відповідь містить secret і standardWebhooksSecret. Збережіть їх одразу: у відкритому вигляді API повертає секрет лише під час створення ендпоінта та ротації його секрету.

2. Підпишіть ендпоінт на тип події.

   curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/subscriptions" \
     -H "X-API-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"endpointId":"'"$ENDPOINT_ID"'","eventType":"order.completed"}'

3. Надішліть подію (див. Надіслати подію нижче). Кожен ендпоінт, підписаний на order.completed, отримає власну доставку.

Поля ендпоінта

Поле	Що робить
url	Обов’язкове. Адреса, на яку надсилаються доставки. Перевіряється на належність до приватних діапазонів адрес, див. Безпека ендпоінта.
description	Довільний текст, до 500 символів.
enabled	Чи отримує ендпоінт доставки.
autoDisabledAt	Лише для читання. Проставляється, коли Railhook вимкнув ендпоінт сам, див. Коли Railhook вимикає ендпоінт. Відсутнє, якщо вимкнули ви.
autoDisabledReason	Лише для читання. Причина, словами.
failingSince	Лише для читання. Початок поточної безперервної серії невдалих доставок; зникає, щойно одна вдасться.
signatureScheme	BOTH (типово), LEGACY або STANDARD: які заголовки підпису надсилаються. Див. Перевірка підписів.
rateLimitPerSecond	Ліміт доставок на секунду для цього ендпоінта, від 0 до 10 000. 0 знімає ліміт.
secret	Необов’язкове. Ваш власний секрет підпису замість згенерованого.
allowedSourceIps	Поле для нотатки. Нічого не обмежує, див. Безпека ендпоінта.

Коли Railhook вимикає ендпоінт

Ендпоінт, який падає вже кілька днів, вимикається, і вас про це повідомляють. Інакше кожна нова подія починала б новий розклад повторних спроб на мертвого отримувача. Мають виконатися обидві умови:

Умова	Типово	Змінна
Жодної успішної доставки протягом	72 години	ENDPOINT_AUTO_DISABLE_AFTER_HOURS
…і в цій серії щонайменше стільки невдалих спроб	10	ENDPOINT_AUTO_DISABLE_MIN_FAILURES

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

Список ендпоінтів і «З’єднання» показують «Вимкнено автоматично» та відколи. API повертає на ендпоінті autoDisabledAt, autoDisabledReason і failingSince.

Що стається з уже поставленими в чергу доставками

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

Ендпоінт, який вимикаєте ви, поводиться інакше: його доставки в черзі завершуються як FAILED, бо ви більше не хочете їх доставляти.

Як увімкнути назад

Повторне ввімкнення знімає автоматичне вимкнення разом із серією невдач, тож наступний прохід не вимкне ендпоінт одразу знову. Скористайтеся кнопкою живлення на ендпоінті або POST /api/v1/projects/{projectId}/endpoints/{id}/enable. Спершу полагодьте отримувача: ендпоінт, який ще падає, почне нову серію.

Кого сповіщають

Сповіщення з’являється на сторінці «Сповіщення» проєкту. Якщо налаштована пошта (EMAIL_ENABLED=true), власники організації також отримують один лист: який ендпоінт, відколи він падає і як увімкнути його назад. Правило сповіщень не потрібне.

Вхідні призначення

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

Як вимкнути цю поведінку

Задайте ENDPOINT_AUTO_DISABLE_ENABLED=false і в api, і у воркері.

Нові ендпоінти й перевірка

Типово новий ендпоінт отримує статус SKIPPED і одразу приймає доставки. Якщо оператор задав WEBHOOK_ENDPOINT_VERIFICATION_REQUIRED=true, новий ендпоінт отримує статус PENDING, і кожна доставка на нього завершується невдачею, доки він не пройде перевірку власника. Див. Безпека ендпоінта.

Поля підписки

Поле	Що робить
endpointId	Обов’язкове. Ендпоінт, який отримує події, що підпадають під підписку.
eventType	Обов’язкове. Точний тип події або шаблон, див. нижче.
enabled	Чи створює підписка доставки.
orderingEnabled	Доставляти події цього ендпоінта в порядку їх створення. Типово вимкнено, див. Порядок доставки.
maxAttempts	Від 1 до 20. Скільки спроб зробити, перш ніж полишити доставку.
retryableStatuses	Які HTTP-статуси варті ще однієї спроби, напр. 408,429,500-599 або 5xx,!501. Див. Які статуси варті повтору.
retryDelays	Інтервали між спробами в секундах через кому, наприклад 60,300,900.
timeoutSeconds	Від 1 до 60, типово 30. Скільки одна спроба чекає на відповідь.
transformationId	Збережена трансформація, яку треба застосувати, див. Трансформації.
payloadTemplate	Вбудований шаблон; діє, коли transformationId не задано.
customHeaders	Додаткові HTTP-заголовки як JSON-об’єкт у рядку.

Без maxAttempts і retryDelays діє типовий розклад повторних спроб для вихідних вебхуків: див. Повторні спроби та недоставлені повідомлення.

Шаблони типів подій

Тип події пишуть малими літерами, він починається з літери, а сегменти розділено крапками: order.completed. Підписка може вказувати на шаблон:

Шаблон	Під нього підпадає
order.completed	Лише цей тип події.
order.*	Рівно один сегмент після order.: order.completed, order.updated. Але не order.line.added.
order.**	Будь-яка кількість сегментів після order.: order.completed, order.line.added.
*	Будь-який тип події з одного сегмента.
**	Усі типи подій у проєкті.

Надіслати подію

Надішліть POST /api/v1/events із полем type та об’єктом data. У відповідь прийде 201. Додавайте заголовок Idempotency-Key, щоб отримувач міг розпізнати дублікат.

Node.js

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

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

const event = await client.events.send(
  { type: 'order.completed', data: { orderId: 'ord_12345', amount: 99.99 } },
  'order-12345-completed',
);

Python

import os

from railhook import Railhook, Event

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

event = client.events.send(
    Event(type="order.completed", data={"order_id": "ord_12345", "amount": 99.99}),
    idempotency_key="order-12345-completed",
)

PHP

<?php
use Railhook\Railhook;

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

$event = $client->events->send(
    type: 'order.completed',
    data: ['orderId' => 'ord_12345', 'amount' => 99.99],
    idempotencyKey: 'order-12345-completed',
);

cURL

curl -X POST "$RAILHOOK_URL/api/v1/events" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-completed" \
  -d '{"type":"order.completed","data":{"orderId":"ord_12345","amount":99.99}}'

Політика ідемпотентності

Налаштування проєкту idempotencyPolicy вирішує, що буде з подією без Idempotency-Key:

Політика	Подія без ключа
NONE	Приймається, ключ не генерується.
AUTO	Приймається й отримує випадковий ключ.
REQUIRED	Відхиляється.

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

Що надходить на ендпоінт

Тіло запиту є об’єктом data події, без обгортки. Ідентифікатори передаються в заголовках:

Доставка

POST /webhooks HTTP/1.1
Content-Type: application/json
X-Signature: t=1738000000000,v1=<hex hmac-sha256>
X-Timestamp: 1738000000000
X-Event-Id: 6f0e…
X-Delivery-Id: 91ab…
X-Sequence-Number: 0
Idempotency-Key: order-12345-completed-<endpoint-id>
webhook-id: 91ab…
webhook-timestamp: 1738000000
webhook-signature: v1,<base64>

{"orderId":"ord_12345","amount":99.99}

Типу події в тілі немає. Розрізняйте події за вмістом або за ендпоінтом чи задайте підписці шаблон, який додає type у тіло.

Idempotency-Key складається з ключа події (або, без нього, ідентифікатора події), - та ідентифікатора ендпоінта. Він однаковий в усіх спробах доставки.

Порада

Щоб перевірити, чи ендпоінт відповідає, до реального трафіку, скористайтеся POST /api/v1/projects/{projectId}/endpoints/{id}/test. Він повертає успіх, HTTP-статус і затримку. Формати запитів і відповідей є в довіднику API.