инструкция · ответ с источниками

Как работают вебхуки Resend?

Вебхуки Resend работают так: когда происходит событие, связанное с письмом, контактом, доменом или стоп-листом, на зарегистрированный вами эндпоинт отправляется HTTPS-запрос POST с полезной нагрузкой события в формате JSON. Эндпоинт должен проверить подпись по «сырому» телу запроса, идемпотентно обработать событие и быстро вернуть успешный ответ.

Как устроена работа с вебхуками Resend

Всё начинается с того, что вы создаёте публичный HTTPS-эндпоинт и регистрируете его в Resend с нужными вашему приложению типами событий. Когда происходит подходящее событие, Resend отправляет POST-запрос с полезной нагрузкой в формате JSON. Она содержит тип, например email.sent, email.delivered, email.bounced или email.complained, время создания и данные, специфичные для события. Маршрутизируйте обработку по полю type, а не рассчитывайте, что все полезные нагрузки имеют одинаковую структуру.

Проверяйте запрос до обработки

Считайте запрос как необработанный текст и проверьте его с помощью секрета подписи вебхука и заголовков svix-id, svix-timestamp и svix-signature. Делайте это до разбора полезной нагрузки и каких-либо действий с ней. Разбор JSON с последующей повторной сериализацией может изменить байты, и тогда легитимная подпись не пройдёт проверку. Отклоняйте запросы, не прошедшие проверку, и храните секрет подписи в менеджере секретов или защищённой переменной окружения, а не в исходном коде.

Сделайте обработку событий идемпотентной

Resend заявляет доставку «как минимум один раз» (at-least-once), поэтому одно и то же событие может прийти на ваш эндпоинт несколько раз. Храните svix-id с ограничением уникальности и пропускайте бизнес-логику, если этот идентификатор уже был обработан. Не полагайтесь и на порядок поступления: повторы и сетевые задержки могут менять порядок событий. Если последовательность важна, используйте значение created_at события и моделируйте смену статусов так, чтобы более старое событие не могло случайно перезаписать более новое состояние.

Подтверждайте быстро, обрабатывайте надёжно

Возвращайте HTTP 200 после того, как событие проверено и надёжно сохранено, а более медленную работу выполняйте через очередь или фоновый обработчик. Тайм-аут или неуспешный ответ вызывает новую попытку доставки, поэтому долгие синхронные обработчики порождают лишние дубликаты. Отделяйте приём событий от побочных эффектов, таких как обновление записи в стоп-листе, уведомление поддержки или регистрация отказа. Каждый побочный эффект тоже должен быть безопасен при повторении или защищён сохранённым идентификатором события.

Тестируйте повторы, повторную доставку и восстановление после сбоев

Перед выходом в продакшен протестируйте эндпоинт на типичных видах событий, включая недействительные подписи, повторяющиеся идентификаторы, метки времени не по порядку и временные сбои базы данных. Resend повторяет неудачные доставки по графику с нарастающей задержкой и позволяет повторно отправить (replay) как неудачные, так и успешные сообщения вебхуков. Используйте повторную отправку для восстановления после сбоя или проверки обновлённого кода обработчика, но не отключайте дедупликацию, чтобы восстановление не повторяло побочные эффекты, заметные клиентам.

Что спрашивают команды

Какой ответ должен возвращать эндпоинт вебхука Resend?

Возвращайте HTTP 200 после того, как запрос проверен, а событие надёжно принято. Медленная работа должна продолжаться асинхронно, чтобы провайдер не делал повтор из-за тайм-аута.

Почему нужно сохранять исходное тело запроса?

Подпись вычисляется по исходным байтам запроса. Разбор и повторная сериализация JSON могут изменить эти байты, и проверка не пройдёт даже для легитимного запроса.

Может ли событие вебхука Resend быть доставлено больше одного раза?

Да. Resend заявляет доставку «как минимум один раз», поэтому обработчики должны дедуплицировать события — как правило, сохраняя уникальный svix-id до применения побочных эффектов бизнес-логики.

Доставляются ли события вебхуков Resend по порядку?

Нет. Сетевые задержки и повторы могут изменить порядок поступления. Если приложению нужно восстановить надёжную последовательность, используйте метки времени событий и правила перехода между состояниями.

Как восстанавливаться после неудачных доставок вебхуков Resend?

Resend автоматически повторяет неудачные доставки, а также поддерживает ручную повторную отправку. Сначала исправьте эндпоинт, затем повторно отправьте нужные события, не отключая проверки идемпотентности.