Вебхук — это HTTPS-запрос, который шлюз отправляет на ваш эндпоинт при событии: доставке или ошибке сообщения, входящем ответе либо низком балансе; отдельно запрашивать статус не нужно.
При опросе (polling) клиент снова и снова спрашивает API, не изменилось ли что-нибудь; чаще всего ответ — «пока нет», каждый такой ответ стоит запроса из лимита, а новости приходят с опозданием. Вебхук меняет направление: вы регистрируете HTTPS-эндпоинт, а шлюз, когда что-то происходит, отправляет на него событие POST-запросом. Каждое событие содержит идентификатор, тип, временную метку и данные и подписано, чтобы вы могли проверить, откуда оно пришло.
Доставка выполняется по принципу «как минимум один раз». Если ваш эндпоинт отвечает медленно или недоступен, событие отправляется повторно, а повтор после медленного, но успешного ответа означает, что одно и то же событие может прийти дважды; порядок тоже не гарантирован. Обработчик, рассчитанный на рабочую среду, учитывает всё это:
- Проверяйте подпись по необработанному телу запроса и отклоняйте устаревшие временные метки.
- Сохраняйте событие и сразу отвечайте 2xx; саму обработку выполняйте из очереди.
- Устраняйте дубликаты по идентификатору события.
- Применяйте изменения статуса только вперёд, чтобы запоздавший «sent» никогда не перезаписал «delivered».
Пример
Условное развёртывание на двадцать минут выводит эндпоинт из строя. События, возникшие за это время, не доставляются, повторяются со всё большими интервалами и доходят, как только эндпоинт снова начинает работать. Обработчик проверяет идентификатор каждого события, применяет те, которых ещё не видел, и ничего не теряется.
Типичные ошибки
- Выполнять долгую обработку до ответа, что приводит к тайм-аутам, повторам и дубликатам.
- Разбирать JSON до проверки подписи.
- Считать, что события приходят по порядку или только один раз.
В SMSMeteor: задокументированы события message.sent, message.delivered, message.failed, message.expired и message.rejected для трафика; campaign.started, campaign.paused и campaign.completed для кампаний; balance.low и balance.credited для учётной записи; для каждого эндпоинта можно выбрать любой набор из них. Входящие сообщения на арендованные номера с приёмом входящих тоже поступают через вебхук. Каждое событие подписывается HMAC-SHA256 в заголовке X-Meteor-Signature, а рядом передаётся X-Meteor-Timestamp. Ваш эндпоинт должен ответить 2xx в течение 5 секунд; иначе доставка повторяется — шесть попыток в течение 24 часов (сразу, затем +1 мин, +5 мин, +30 мин, +2 ч и +12 ч), после чего событие помечается как недоставленное. Недоставленные события 30 дней хранятся в панели в списке по каждому эндпоинту, и их можно повторно отправить по одному или массово с сохранением исходного идентификатора события. Вебхуки, запускаемые тестовыми ключами, подписываются так же, как рабочие. См. документацию по вебхукам.
Связанные термины
- HMAC-подпись вебхуков
- Отчёт о доставке (DLR)
- Экспоненциальная задержка повторных запросов
- Идентификатор запроса
