Підпис webhook і вікно replay: ідемпотентність, щоб 02:00 було нудним

Непідписані callback — не події. Це неавтентифікований HTTP, який випадково схожий на ваш payload. Команди, які «спочатку приймемо, підпис потім», дізнаються ціну о 02:00: повторний DLR, подвоєний STOP або другий debit гаманця, який фінанси не розмотають. Prepaid messaging робить збій видимим у грошах. Нудні звички: перевірка підпису на кожному запиті, обмежене вікно replay і ключі ідемпотентності, які фінанси читають поруч із рядком ledger.

IOSOR очікує аудивані B2B-інтеграції: підписані webhook, ротовані секрети, client-safe помилки без чужих брендів. Біля USD 1 000+ місячного platform usage correlation ID і evidence replay стають матеріалом комерційного review — не лише інженерною гігієною. Тримайте поруч вебхуки й ключі на запуску і вебхуки, що переживають запуск.

Непідписані callback — не події

Перевіряйте підпис до розбору бізнес-полів. Відхиляйте відсутні, протухлі або незбіжні підписи client-safe помилкою — не обробляйте «все одно, це пілот». Staging-consumer, який пропускає verification, вчить production пропускати її. Каталог live для messaging не робить ваш webhook URL публічним звалищем. Якщо не можете довести, хто підписав тіло, у вас немає події — є підроблений запит.

Вікна replay і чому трапляється 02:00

At-least-once доставка ретраїть за timeout, 5xx і неоднозначною втратою мережі. Пізній retry о 02:00 — норма. Вікно replay обмежує, як довго підписаний payload ще прийнятний: занадто широке — атакувальник повторить старий STOP; занадто вузьке — легітимний retry виглядає підробкою. Логуйте відмови вікна окремо від провалів підпису. Див. повторні спроби вхідного вебхука. Відповідайте швидко, persist спочатку, обробляйте async — handler, який чіпає CRM до ACK, сам виробляє дублікати.

Ідемпотентність, яку фінанси можуть прочитати

Той самий event ID має давати той самий кінцевий стан. Беріть platform event/message ID — ніколи не вигадуйте ключ із timestamp плюс body. На відомий ID повертайте success без повторного debit. Вихідні send вимагають тієї ж дисципліни — ідемпотентність, retry і гроші. Фінанси мають пояснити кожен prepaid-рядок проти status event. Якщо timeout викликає client retry storm, ledger покаже шкоду першим. Каталог in setup — не відмовка пропустити ідемпотентність «до Live».

Ротація підпису без хаосу dual-accept

Ротуйте секрети без вікна, де старий і новий підписи приймаються вічно. Сплануйте overlap, потім cut. Ніколи не вставляйте production-секрет у тікет підтримки. Розведіть sandbox і production consumers. Dead-letter з інструментом replay, щоб ops міг повторно прогнати failed consumer без другого debit. Ведіть correlation ID від send до рядка ledger, щоб 02:00 був runbook, а не археологія.

Червоні прапорці

• Handler приймає непідписані тіла «поки що»
• Немає вікна replay або вікно вимірюється тижнями
• Перезапис статусу без порівняння timestamp
• Side effects у CRM/email до ACK
• Спільний production-секрет у чаті
• Дублі event ID за місяць, і ніхто не дивиться
• Client-facing помилки з сирими upstream-кодами

Почніть з IOSOR

Відкрийте налаштування вебхуків у консолі IOSOR та додайте перевірку HMAC-підпису до того, як ваш обробник читатиме вміст сповіщень про статус доставки. Налаштуйте часове вікно повтору у межах п'яти хвилин для відсікання застарілих запитів та зафіксуйте оригінальний ідентифікатор події як ключ ідемпотентності. Перевірте роботу журналів DLR у консолі, щоб переконатися, що нічні повторні спроби відправки не призводять до дублювання бізнес-логіки.

Підсумок IOSOR

Ця стаття доводить, що надійність обробки вебхуків о 02:00 залежить від жорсткої перевірки HMAC-підпису та чітко обмеженого часового вікна прийняття повторів.