Разработчикам и API

Вебхуки

Вебхуки доставляют события на ваш бэкенд в момент, когда они происходят, — сообщение доставлено, по ссылке кликнули, контакт отписался. Каждый payload подписан, чтобы ему можно было доверять, а неудачные доставки повторяются с нарастающей паузой, поэтому короткий сбой не теряет событие.

7 мин чтения

Что понадобится

Публичный HTTPS-эндпоинт для приёма POST-запросов
API-ключ или доступ администратора, чтобы зарегистрировать вебхук

Зарегистрируйте эндпоинт

1
Откройте «Настройки» → «Вебхуки»
Или вызовите POST /v1/workspaces/{workspace_id}/webhooks. Укажите свой HTTPS-URL и выберите нужные события.
2
Сохраните секрет подписи
У каждого вебхука есть секрет, показываемый при создании. Им вы будете проверять каждый входящий запрос.
3
Добавьте свои заголовки (по желанию)
Прикрепите заголовки (например, токен авторизации), которые Climails будет слать с каждой доставкой на ваш эндпоинт.

На какие события можно подписаться

Email — email.delivered, email.bounce, email.complaint, email.unsubscribe, email.opened, email.clicked.
SMS — sms.delivered, sms.failed.
Контакты — contact.subscribed, contact.unsubscribed, contact.changed.
Рассылки — campaign.finished.

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

Каждый запрос несёт X-Senderbox-Timestamp и X-Senderbox-Sig. Пересчитайте HMAC и сравните — отклоняйте всё, что не совпало, и отклоняйте старые таймстемпы, чтобы исключить повтор.

X-Senderbox-Sig: sha256=<hex>

// signature = HMAC_SHA256(secret, timestamp + "." + rawBody)
import crypto from "node:crypto";

function verify(rawBody, headers, secret) {
  const ts  = headers["x-senderbox-timestamp"];
  const sig = headers["x-senderbox-sig"]; // "sha256=<hex>"
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(ts + "." + rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Хешируйте сырое тело запроса ровно как пришло — не пересериализуйте JSON, иначе подпись не совпадёт.

Ретраи и сбои

Быстро верните 2xx для подтверждения. Если ваш эндпоинт ответил ошибкой или не успел, Climails повторяет с нарастающей паузой: 30с, 2м, 10м, 1ч, 6ч, 24ч.

После 6 неудачных попыток доставка отбрасывается.
Ответ 4xx (кроме 408 и 429) считается финальным и не повторяется — почините эндпоинт, и доставка возобновится со следующего события.
Эндпоинты защищены от SSRF: внутренние и приватные адреса отклоняются.

Частые вопросы

Как убедиться, что вебхук действительно от Climails?

Пересчитайте HMAC-SHA256 по timestamp + "." + сырое тело с секретом вебхука и сравните с X-Senderbox-Sig. Сравнивайте за постоянное время.

Что если мой сервер недоступен?

Доставки повторяются с паузой (30с → 24ч) до 6 попыток, поэтому короткий сбой не потеряет события.

Почему вебхук сразу перестал повторяться?

Ответ 4xx (кроме 408/429) считается постоянной ошибкой. Почините обработчик — новые события снова начнут доставляться.

Материалы

Шаблоны писем Сценарии Решения Бесплатные инструменты Словарь Блог Все интеграции

Начните отправлять за минуты

Заведите бесплатный аккаунт, подключите домен и охватите аудиторию во всех каналах — карта не нужна.

Начать бесплатно

Бесплатный тариф навсегда · Без карты · Запуск за минуты