Типи подій
Кожна подія має тип — order.created, stripe.invoice.paid, — а ендпоінти підписуються на типи за шаблоном. Каталог типів подій — це список назв, які використовує ваш робочий простір, з необовʼязковим описом і JSON Schema для кожної. Тут же ви вирішуєте, що відбувається, коли зʼявляється назва, яку ніхто не реєстрував.
Чи треба реєструвати типи?
Ні — за політики за замовчуванням не треба. З Lenient будь-який тип, який ви публікуєте (або який отримує джерело), приймається й додається до каталогу, щойно зʼявляється вперше. Більшість робочих просторів ніколи не реєструють типи вручну.
Реєструйте тип, коли хочете:
- описати його для тих, хто будує інтеграції з вашими вебхуками;
- перевіряти його payload-и за JSON Schema (нижче);
- або перейти на Strict, де можна публікувати лише зареєстровані типи.
Підписки ендпоінтів у будь-якому разі зіставляються за назвою; підписці на order. не потрібно, щоб order.created був у каталозі.
Політика для незареєстрованих типів
| Політика | Незареєстрований тип… |
|---|---|
| Lenient (за замовчуванням) | приймається й додається до каталогу. |
| Strict | відхиляється з 422 unknown_event_type. |
Strict підходить робочому простору, де набір типів — це контракт: тоді одрук у продюсері гучно провалюється під час публікації, а не тихо створює тип, на який не підписаний жоден ендпоінт. Запит джерела, відхилений у такий спосіб, показується як unknown_event_type у перехоплених запитах.
Політика задається для робочого простору, а також її можна задати для окремого проєкту (PUT /v1/event-types/policy, з ?project_id= для одного проєкту). У консолі це елемент керування When an unregistered type arrives на сторінці Event types, і він відповідає проєкту, вибраному в перемикачі проєктів.
Схеми payload-у
Тип може мати JSON Schema (draft 7). Коли схема є, кожна публікація цього типу перевіряється за нею, а payload, що не відповідає, відхиляється з 422 invalid_payload зі списком того, що не пройшло перевірку.
curl -sX POST https://webhooks.nimbusnexus.net/v1/event-types \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order.created",
"description": "A customer placed an order",
"payload_schema": {
"type": "object",
"required": ["order_id", "total"],
"properties": {"order_id": {"type": "string"}, "total": {"type": "integer"}}
}
}'Схеми перевіряються під час збереження: схема, яка не є коректною JSON Schema або чиї регулярні вирази можуть зробити зіставлення надзвичайно повільним, відхиляється з поясненням.
Типи для всього робочого простору й для окремого проєкту
Тип, зареєстрований без проєкту, діє для всіх проєктів. Тип, зареєстрований з project_id, діє лише для цього проєкту й має там пріоритет над записом з тією самою назвою для всього робочого простору, тож проєкт може мати власний опис чи суворішу схему. Стовпець Applies to у консолі показує, який тип до чого застосовується.
Звідки взявся тип
| Походження | У консолі | Як він туди потрапив |
|---|---|---|
manual | added here | Зареєстрований у консолі або через POST /v1/event-types. |
ingest | from a source | Уперше надійшов через джерело за політики Lenient. |
lenient | auto-added | Уперше опублікований через API за політики Lenient. |
webhook.received
Якщо в каталозі є webhook.received, а ви його ніколи не публікували, отже, джерело отримало запити, з яких не змогло прочитати тип, і не мало типу за замовчуванням, щоб його підставити. Задайте цьому джерелу тип за замовчуванням або вкажіть йому заголовок чи JSON-шлях, де міститься тип, — див. Типи подій із джерела.
Що далі
- Джерела — як джерело читає тип із запиту провайдера.
- Огляд Webhooks — підписки та інші обʼєкти.
- Помилки —
unknown_event_type,invalid_payloadта інші.