Перехід на Railhook
Складність переходу визначають дві речі: чи треба змінювати ваші приймачі і чи переносяться ваші поняття. Ця сторінка розбирає обидві, а потім дає план міграції, який можна виконати, поки обидві платформи працюють.
Ваші приймачі зазвичай працюють далі
Section titled “Ваші приймачі зазвичай працюють далі”Railhook підписує вихідні доставки заголовками Standard Webhooks:
webhook-id: <the delivery id, unchanged across retries>webhook-timestamp: <unix seconds>webhook-signature: v1,<base64>Підпис — це HMAC-SHA256 над {id}.{timestamp}.{body}, закодований у base64. Приймач, який уже перевіряє підписи бібліотекою Svix або Standard Webhooks, працює далі, щойно отримає новий секрет.
Нові ендпоінти за замовчуванням також отримують власний заголовок Railhook:
X-Signature: t=<unix milliseconds>,v1=<hex HMAC-SHA256 of "{t}.{body}">Приймач перевіряє відомий йому заголовок і ігнорує інший, тож переводити приймачі можна по одному — або не переводити зовсім.
| Ваш приймач перевіряє підпис через | Що змінити |
|---|---|
| Бібліотеку Svix або Standard Webhooks | Секрет і URL. Більше нічого. |
| Власний заголовок підпису іншої платформи | Перейдіть на бібліотеку Standard Webhooks або перевіряйте X-Signature. Надсилаються обидва. |
Власноруч написаний розбір t=…,v1=… |
Перевірте одиниці: t в X-Signature — у мілісекундах, а не в секундах. |
Приймачі мають дедуплікувати за webhook-id. Доставка — щонайменше один раз, а ідентифікатор не змінюється між повторами.
Код перевірки для кожної мови SDK — на сторінці Підписи.
Як відповідають поняття
Section titled “Як відповідають поняття”| Railhook | Svix | Hookdeck | Convoy |
|---|---|---|---|
| Організація | — | — | Organisation |
| Проєкт | Application | — | Project |
| Ендпоінт | Endpoint | Destination (Outpost) | Endpoint |
| Підписка (ендпоінт і тип події) | Типи подій на ендпоінті | — | Subscription |
| Подія | Message | Event | Event |
| Доставка (одна подія на один ендпоінт) | — | — | Event delivery |
| Спроба (один HTTP-запит) | Attempt | Attempt | — |
| Джерело (провайдер, від якого ви приймаєте) | Source (Ingest) | Source (Event Gateway) | Source |
| Призначення (куди йде отриманий вебхук) | Destination (Ingest) | Destination (Event Gateway) | — |
| Машина часу (повтор) | Replay | — | — |
Прочерк означає, що ми не знайшли прямого відповідника в документації постачальника, а не що в нього немає такої можливості.
Під час переходу важать дві відмінності:
- Доставка і спроба — окремі речі. Доставка — це зобов’язання донести одну подію до одного ендпоінта; спроба — один HTTP-запит у її межах. На запитання «скільки разів це повторювали» є точна відповідь.
- Повтор через Машину часу — не повторна спроба. Повторна спроба — наступна спроба тієї самої доставки. Машина часу будує нову доставку зі збереженої події й лишає оригінал як є. Див. Машина часу.
Міграція без вікна обслуговування
Section titled “Міграція без вікна обслуговування”Оскільки приймачі вміють перевіряти обидві схеми підпису, стара платформа й Railhook можуть працювати паралельно.
- Відтворіть структуру. Створіть проєкти, ендпоінти й підписки через API. Див. Ендпоінти та підписки.
- Дайте кожному приймачу новий секрет у форматі
whsec_. Тепер він приймає підписи обох платформ. - Надсилайте кожну подію на обидві платформи, скільки потрібно для впевненості. Приймач, що дедуплікує за
webhook-id, обробляє кожну доставку Railhook один раз. - Порівняйте. Стежте за
delivery_oldest_pending_age_secondsі невдалими повідомленнями в Railhook поряд із цифрами старої платформи. Див. Спостережуваність. - Припиніть надсилати на стару платформу. Моменту перемикання немає.
Перш ніж вирішити
Section titled “Перш ніж вирішити”Перегляньте Railhook у порівнянні: там сказано, чого в Railhook поки немає, — наприклад, порталу для клієнтів, SSO і не-HTTP призначень.