Портал для клієнтів

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

Кожного вашого користувача Railhook називає споживачем (Consumer). Споживач об’єднує ендпоінти, зареєстровані для цього користувача, а сесія порталу — це короткочасні облікові дані, з якими портал діє від імені рівно одного споживача.

Як це працює разом

Ваш бекенд створює споживача для кожного користувача, який отримує вебхуки, і прив’язує його до вашого власного id користувача.
Коли цей користувач відкриває сторінку вебхуків у вашому продукті, ваш бекенд за допомогою свого API-ключа відкриває сесію порталу для його споживача.
Ваша сторінка вставляє url сесії в <iframe>. Портал працює всередині нього й звертається до Railhook лише з токеном сесії.

Як створити споживача

POST /api/v1/projects/{projectId}/consumers приймає externalId і необов’язковий name. externalId — це ваш власний id користувача, унікальний у межах проєкту, тож бекенд може знайти споживача, не зберігаючи id з Railhook: його повертає GET /api/v1/projects/{projectId}/consumers?externalId=user_123. name показується вгорі порталу й типово дорівнює externalId. Другого споживача з тим самим externalId створити не вийде: API відповість 409.

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

const railhook = new Railhook({
  apiKey: process.env.RAILHOOK_API_KEY,
  baseUrl: 'https://railhook.io', // or your instance
});

const consumer = await railhook.consumers.create(projectId, { externalId: 'user_123', name: 'Acme Ltd' });

import os

from railhook import ConsumerCreateParams, Railhook

client = Railhook(
    api_key=os.environ["RAILHOOK_API_KEY"],
    base_url="https://railhook.io",  # or your instance
)

consumer = client.consumers.create(
    project_id,
    ConsumerCreateParams(external_id="user_123", name="Acme Ltd"),
)

<?php
use Railhook\Railhook;

$client = new Railhook(
    apiKey: getenv('RAILHOOK_API_KEY'),
    baseUrl: 'https://railhook.io', // or your instance
);

$consumer = $client->consumers->create($projectId, ['externalId' => 'user_123', 'name' => 'Acme Ltd']);

curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/consumers" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"user_123","name":"Acme Ltd"}'

Як передати ендпоінти споживачеві

Споживач може сам реєструвати ендпоінти в порталі. Ендпоінти, якими ви вже керуєте від імені користувача, з’являться в його порталі, щойно ви задасте їм consumerId під час створення чи оновлення:

curl -X PUT "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/endpoints/$ENDPOINT_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.acme.example/railhook","consumerId":"'"$CONSUMER_ID"'"}'

Споживач має належати до того самого проєкту, що й ендпоінт; на будь-якого іншого API відповість 404. Якщо в запиті на оновлення немає consumerId, ендпоінт лишається там, де був. Ендпоінти споживача повертає GET /api/v1/projects/{projectId}/consumers/{consumerId}/endpoints.

Ендпоінт без споживача належить лише вам: він не з’являється в жодному порталі.

Як відкрити сесію порталу

Відкривайте сесію зі свого бекенда щоразу, коли користувач завантажує сторінку, запитом POST /api/v1/projects/{projectId}/consumers/{consumerId}/portal-sessions. Тіло запиту необов’язкове:

Поле	Типово	Значення
`ttlMinutes`	`60`	Скільки триває сесія, від 1 до 1440 (24 години).
`allowedOrigin`	немає	Origin сторінки, у яку вбудовано портал, наприклад `https://app.example.com`. Якщо його задано, портал відображається лише всередині цієї сторінки.

Відповідь містить id, consumerId, url, token, allowedOrigin і expiresAt. Токен є лише в цій відповіді: Railhook зберігає тільки його SHA-256-хеш.

const session = await railhook.portalSessions.create(projectId, consumer.id, {
  ttlMinutes: 60,
  allowedOrigin: 'https://app.example.com',
});
// session.url → hand it to your page

from railhook import PortalSessionCreateParams

session = client.portal_sessions.create(
    project_id,
    consumer.id,
    PortalSessionCreateParams(ttl_minutes=60, allowed_origin="https://app.example.com"),
)
# session.url → hand it to your page

$session = $client->portalSessions->create($projectId, $consumer['id'], [
    'ttlMinutes' => 60,
    'allowedOrigin' => 'https://app.example.com',
]);
// $session['url'] → hand it to your page

curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/consumers/$CONSUMER_ID/portal-sessions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlMinutes":60,"allowedOrigin":"https://app.example.com"}'

Відкриття сесії — це операція запису, тому потрібен API-ключ із доступом READ_WRITE.

Як вбудувати портал

Вставте url в iframe на своїй сторінці:

<iframe
  src="https://railhook.example.com/portal?origin=https://app.example.com#rhp_…"
  style="width: 100%; height: 720px; border: 0"
  title="Webhooks"
></iframe>

URL має вигляд <APP_BASE_URL>/portal#<token> або <APP_BASE_URL>/portal?origin=<allowedOrigin>#<token>, якщо для сесії задано дозволений origin. Токен передається у фрагменті після #, який браузер ніколи не надсилає на сервер, тож він не потрапляє ні в логи доступу, ні в заголовок Referer. Щойно портал завантажиться, він прибирає токен з адресного рядка й тримає його лише в пам’яті.

Щоб показати портал поза вашим продуктом, наприклад з інструмента підтримки, відкрийте url у новій вкладці: сесія без allowedOrigin працює і як окрема сторінка, і у фреймі.

Оформлення в стилі вашого продукту

Додайте ці параметри в URL перед #:

Параметр	Значення
`primary`	Колір вашого бренду в hex-форматі, 3 або 6 цифр: `primary=1D4BFF` або з `#`, закодованим як `%23`.
`logo`	`https://`-адреса зображення для шапки порталу.
`theme`	`light` або `dark`. Без цього параметра портал бере тему із системних налаштувань користувача.
`lang`	`en` або `uk`. Без цього параметра портал бере мову браузера користувача, а якщо вона не підтримується — англійську.

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

https://railhook.example.com/portal?origin=https://app.example.com&primary=1D4BFF&theme=dark&lang=uk#rhp_…

Що може споживач

Споживач може:

бачити власні ендпоінти, створювати, редагувати й видаляти їх: URL, опис, увімкнення й типи подій, які отримує кожен із них;
один раз побачити секрет підпису ендпоінта, коли ендпоінт створено або секрет ротовано;
переглядати доставки на свої ендпоінти з фільтром за статусом;
бачити кожну спробу доставки з її запитом і відповіддю, замаскованими за правилами маскування PII проєкту;
повторити невдалу доставку, і вона знову піде за своїм розкладом повторних спроб.

Споживач не може:

бачити чи змінювати ендпоінти й доставки іншого споживача або власні ендпоінти проєкту;
задавати ліміт запитів, список дозволених IP, mTLS чи схему підпису (це лишається на ваш розсуд);
звертатися до будь-чого поза /api/v1/portal/. Токен сесії не дає доступу ні до чого іншого, а сесію панелі керування чи API-ключ маршрути порталу не приймають.

Якщо ваш проєкт оголошує свої типи подій у реєстрі схем, портал пропонує саме їх і не приймає інших; шаблон на кшталт order.* приймається, якщо під нього підпадає оголошений тип. Якщо не оголошено жодного, портал пропонує типи, які проєкт надсилав за останні 7 днів, і ті, на які вже підписані його ендпоінти.

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

Модель безпеки

Токен. 32 випадкові байти з префіксом rhp_. Як і API-ключ, токен повертається один раз і зберігається лише як SHA-256-хеш.
Тривалість. Від 1 хвилини до 24 годин. На запити простроченої сесії API відповідає 401, і портал показує, що сесія завершилася. Відкрийте нову.
Відкликання. DELETE /api/v1/projects/{projectId}/consumers/{consumerId}/portal-sessions одразу завершує всі відкриті сесії споживача. Зробіть це, якщо токен міг витекти. Видалення споживача теж завершує його сесії й видаляє його ендпоінти, щоб доставки не йшли користувачеві, якого вже немає.
Де можна вбудувати. allowedOrigin — це https://-origin, а на час розробки — http://localhost чи http://127.0.0.1 з будь-яким портом. Якщо його задано, сторінка порталу віддається із заголовком Content-Security-Policy: frame-ancestors <цей origin>, тож браузер не покаже її всередині жодної іншої сторінки, а сам портал не відобразиться, якщо origin у його URL не збігається з origin сесії. Якщо не задано, портал може вбудувати будь-яка https://-сторінка та http://localhost. Решту сторінок Railhook жоден сторонній сайт не може вбудувати у фрейм.
Ліміт запитів. Запити порталу лімітуються окремо для кожної сесії, тож скрипт, який у циклі шле запити з одним токеном, вичерпує власний ліміт, а не ліміт вашої панелі керування.

Маршрути API порталу перелічено в розділі Portal, а ті, що викликає ваш бекенд, — у розділі Consumers довідника API.