IOSOR

IOSOR База знань

Webhook inbound SMS: ретраї, порядок подій та ідемпотентність на прийомі

Посібник з розробки для B2B-команд, що обробляють вхідні SMS: чому трапляються ретраї, чому порядок подій не гарантований, і як зробити приймальний endpoint ідемпотентним замість дублювання переписки та обробки STOP.

Кожен обробник вхідних повідомлень рано чи пізно стикається з тими самими трьома несподіванками: той самий webhook спрацьовує двічі, подія «delivered» приходить після події «failed», яку вона мала замінити, а відповідь клієнта STOP обробляється двічі, бо два сервери підхопили той самий ретрай. Жодне з цього не є багом платформи, що надсилає webhook, — це нормальна поведінка будь-якої системи доставки «at-least-once», і ваш приймальний endpoint має бути побудований з урахуванням цієї реальності з першого дня.

IOSOR доставляє вхідні SMS, ключові слова STOP/HELP та події доставки як white-label передплачені webhooks — поведінка з ретраями та порядком нижче — це те, що має закладати будь-яка серйозна B2B-інтеграція незалежно від того, яка платформа стоїть за нею.

Чому webhooks взагалі роблять ретраї

Провайдер webhook не може бути впевненим, що ваш endpoint обробив доставку. Ваш сервер може повернути 200 після коміту в базу даних, яка потім відкочується; балансувальник навантаження може загубити відповідь на зворотному шляху, хоча ваш обробник успішно завершився; деплой може перезапустити процес посеред запиту.

Три режими збою, для яких потрібно проєктувати

Режим збою Що відбувається Що ламається, якщо ігнорувати
Дублююча доставка Той самий ID події приходить 2+ рази Двічі пораховані відповіді, дубльована обробка STOP, дубльовані треди переписки
Події поза порядком Подія з пізнішою міткою часу приходить раніше за попередню Статус «delivered» перезаписується назад на «sent»
Частковий/неоднозначний збій

Ідемпотентність: одна властивість, що вирішує всі три проблеми

Ідемпотентний приймальний endpoint дає той самий кінцевий стан незалежно від того, скільки разів доставлено ту саму подію. Механізм простий і добре вивчений: кожна вхідна подія несе унікальний ID події; перед обробкою ви перевіряєте, чи вже записували цей ID; якщо так, ви повертаєте успіх негайно без повторної обробки. 1.

Порядок подій: чому «останній запис перемагає» небезпечно

Webhook-події для одного й того самого повідомлення не гарантовано приходять у порядку, в якому вони відбулися. Ретрай раннішої події «queued» може прийти після пізнішої події «delivered» через мережевий джиттер, черги на боці провайдера або те, що ваш власний пул воркерів обробляє запити не за порядком.

STOP, HELP та інші вхідні ключові слова потребують тієї ж дисципліни

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

Почніть з IOSOR

Вивантажте логи вхідних webhook за тиждень і порахуйте ID подій, що прийшли більше одного разу. Програйте один дубль і одну пару не по порядку (failed, потім delivered). Приймач тримає один ефект: один рядок inbox, один запис STOP, один дотик гаманця. Last-write-wins, який відкочує STOP, — провал. Це ідемпотентність на прийомі й порядок ретраїв, не перевірка підпису і не замок шлюзу до черги.

Підсумок IOSOR

Вхідні webhook роблять ретраї. Ідемпотентність на прийомі — єдина безпечна відповідь; порядок не обіцяний.

Робіть: ключуйте подію й ігноруйте близнюка. Не робіть: last-write-wins на STOP або два списання за одну подію.

Чи був матеріал корисним?

Пов’язані гіди