Порядок доставки

Увімкніть порядок для підписки, коли отримувач мусить бачити події ендпоінта в порядку їхнього створення. Типово він вимкнений, діє в межах ендпоінта й стосується лише вихідних доставок.

Як увімкнути

Задайте orderingEnabled у підписці:

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.*","orderingEnabled":true}'

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

Як це працює

Термін	Значення
Порядковий номер	Позиція, яку отримує кожна доставка на ендпоінт. Вона визначає, яка з двох доставок на той самий ендпоінт була першою, незалежно від того, коли воркер їх узяв. Надсилається як X-Sequence-Number і дорівнює 0, коли порядок вимкнено.
Буфер порядку	Місце, де доставка чекає, поки доставки попереду не завершилися. Очікування — це відкладення: воно не витрачає спробу.
Розрив	Діапазон між останньою позицією, яку отримав ендпоінт, і доставкою, що чекає, у якому є принаймні одна незавершена доставка. Перевіряється весь діапазон, а не лише позиція безпосередньо перед.

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

Коли розрив ніколи не закривається

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

Налаштування	Типово
ORDERING_GAP_TIMEOUT_SECONDS	60
Метрика	webhook_ordering_gap_timeout_total

Гарантія поступається, а не блокує

Ендпоінт, що не отримує взагалі нічого, — гірша відмова, тому порядок порушується навмисно. Поодиноке зростання webhook_ordering_gap_timeout_total очікуване. Стале зростання означає, що щось попереду в послідовності не завершується, і ендпоінт насправді не отримує впорядкованої доставки.

Чого це коштує

Ціна	Чому
Пропускна здатність	Впорядкований ендпоінт фактично послідовний. Його власний час відповіді стає вашою стелею.
Блокування голови черги	Одна повільна чи невдала доставка тримає все, що за нею, доки не завершиться або доки не спрацює тайм-аут розриву.
Повтори йдуть у кінець	Повтор подій створює нові доставки з новими порядковими номерами, тож повторена подія приходить після того, що вже чекає, а не на своє початкове місце.

Що обіцяно, а що ні

• Порядок діє в межах ендпоінта, ніколи не глобально. Два ендпоінти, підписані на одну подію, отримують її незалежно.
• Доставка й далі at-least-once. Отримувач може побачити ту саму доставку двічі й має дедуплікувати за X-Delivery-Id або Idempotency-Key.
• Порядок — best-effort через тайм-аут розриву. Якщо потрібен порядок, який ніколи не поступається, додайте власне поле послідовності в payload і перевіряйте його в отримувачі.
• У вхідному напрямку порядку немає. Railhook не створював вебхуки провайдера й не може знати, який порядок той мав на увазі. Скористайтеся власним полем послідовності провайдера, якщо воно є.

Що далі

Повторні спроби та невдалі повідомленняЯк завершується невдала доставка й перестає блокувати.

Повтор і Машина часуЧому повторена доставка отримує нову позицію.

СпостережуваністьДе стежити за лічильником тайм-аутів розриву.