Webhook — это не «API наоборот». Это обещание: когда у нас произойдёт событие, мы попробуем сообщить вам об этом

Это не редкость.

Провайдер не получил 2xx.

Сеть оборвалась.

Retry policy отправила событие повторно.

Consumer обязан распознать, что business event уже обработан.

Поэтому event ID и идемпотентность — базовая часть webhook handler.

`shipment.delivered`

может оказаться обработан раньше задержавшегося

`shipment.in_transit`.

Если порядок важен, одной доставки недостаточно.

AMPE использует:

version;

sequence;

timestamp;

state check;

re-fetch current state —

в зависимости от возможностей провайдера.

Webhook endpoint не должен выполнять тяжёлую бизнес-операцию до ответа внешнему сервису.

Иначе timeout провайдера запускает retry и создаёт лишние повторы.

Типичная сильная схема:

принять;

проверить подпись;

зафиксировать;

поставить во внутреннюю очередь;

ответить 2xx;

обработать асинхронно.

Сложный URL не доказывает источник запроса.

AMPE использует поддерживаемую провайдером схему подписи:

HMAC;

certificate;

signed token;

другой verified mechanism.

И проверяет подпись до применения бизнес-эффекта.

Один и тот же корректно подписанный запрос злоумышленник может повторить позже.

Поэтому подпись часто должна включать timestamp или nonce.

Consumer контролирует допустимое окно времени и уже обработанные event IDs.

Провайдер может прислать:

`payment.updated`

и только ID платежа.

Тогда consumer после webhook делает authenticated API call и получает актуальное состояние.

Это нормальная модель.

Webhook сообщает «что-то изменилось», API подтверждает «что именно сейчас истинно».

Платёжный webhook особенно показателен.

Даже валидная доставка может потребовать дополнительной проверки:

суммы;

валюты;

order ID;

current state;

статуса у provider.

AMPE отделяет получение сигнала от подтверждения бизнес-факта.

Через сколько секунд повтор.

Сколько попыток.

Как долго хранится событие.

Есть ли manual replay.

Есть ли event history.

Без этого невозможно правильно спроектировать recovery.

Сканеры.

Ошибочные запросы.

Старые версии.

Некорректный JSON.

AMPE ограничивает:

размер body;

content type;

method;

rate;

schema;

authentication/signature.

Webhook endpoint — публичная граница и должен быть устойчивым.

Провайдер добавит поля.

Иногда изменит event type.

Иногда выпустит новую API version.

Parser не должен ломаться от безопасного расширения payload.

Версия и compatibility policy учитываются заранее.

Мы должны видеть:

получили ли webhook;

и

применили ли бизнес-результат.

Это разные статусы.

Webhook accepted может быть зелёным, а внутренняя обработка — лежать в retry несколько часов.

AMPE связывает transport event с internal processing state.

Webhook даёт быстрый сигнал.

Периодическая reconciliation проверяет, что ничего не потерялось.

Для критичных внешних интеграций это часто сильнее, чем полная вера в один канал доставки.

Внешняя система создаёт событие.

Webhook handler проверяет источник.

Фиксирует event ID.

Передаёт событие во внутренний надёжный контур.

Business handler проверяет текущее состояние.

Применяет результат идемпотентно.

Reconciliation при необходимости подтверждает полноту.

Так ненадёжный HTTP callback становится частью надёжного процесса.

Polling можно уменьшить.

Внешние статусы приходят быстрее.

Повторная доставка не создаёт дубль.

Поддельные запросы отсеиваются.

Тяжёлая обработка не блокирует endpoint.

Потерянные события можно обнаружить сверкой.

И главное — webhook перестаёт быть «магической кнопкой уведомления» и становится управляемым интеграционным каналом.