Сначала проверьте подпись
Каждое событие содержит два заголовка — X-Meteor-Timestamp и X-Meteor-Signature; заголовок подписи имеет вид t=…,v1=…, а сравнивать нужно шестнадцатеричный дайджест после v1=. Подпись — это HMAC-SHA256 от временной метки, точки и необработанного тела запроса, вычисленный с секретом вашей конечной точки в качестве ключа. Вычислите её заново, сравните за постоянное время и отклоняйте временные метки старше пяти минут, чтобы перехваченный запрос нельзя было воспроизвести позже. Делайте это до разбора тела: после разбора и повторной сериализации тело не совпадёт, даже если выглядит идентично. Во Flask необработанное тело доступно через request.get_data(), в Django — через request.body; в Express подключите парсер необработанного тела на маршруте вебхука.
import hashlib, hmac, os, time
# Список через запятую: на время смены секрета в нём могут быть два секрета.
SECRETS = [s.encode() for s in os.environ["WEBHOOK_SECRETS"].split(",")]
def verify(raw_body, timestamp, signature):
# X-Meteor-Timestamp — секунды Unix; X-Meteor-Signature — "t=...,v1=<hex digest>".
try:
ts = int(timestamp)
except (TypeError, ValueError):
return False
if abs(time.time() - ts) > 300: # пять минут
return False
given = (signature or "").split("v1=")[-1].encode()
signed = timestamp.encode() + b"." + raw_body
for secret in SECRETS:
expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
if hmac.compare_digest(expected.encode(), given):
return True
return FalseТа же проверка на Node:
const crypto = require("crypto");
function verify(rawBody, timestamp, signature, secrets) {
const ts = Number(timestamp);
if (Number.isNaN(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
const given = Buffer.from(String(signature || "").split("v1=").pop());
return secrets.some((secret) => {
const expected = Buffer.from(crypto.createHmac("sha256", secret)
.update(timestamp + ".").update(rawBody).digest("hex"));
return expected.length === given.length && crypto.timingSafeEqual(expected, given);
});
}Если проверка не прошла, отвечайте 401 и записывайте в журнал причину, но никогда не сам секрет. Форматы заголовков описаны в документации по вебхукам, а принцип объясняется в статье глоссария о HMAC-подписи.
Быстро подтвердите приём
У вас есть 5 секунд, чтобы ответить любым кодом 2xx. Не выполняйте работу внутри запроса: проверьте подпись, запишите событие в очередь или таблицу и верните 200. Обработчик, который синхронно обновляет три системы, превысит время ожидания в тот день, когда одна из них замедлится, и каждый тайм-аут превратится в повторную попытку, которая может прийти, пока первая ещё выполняется.
Арифметика это подтверждает. Допустим, кампания из 100 000 сообщений порождает до двух событий на сообщение — Отправлено, затем Доставлено или Ошибка: всего 200 000 запросов. Если распределить их на час, в среднем это около 56 запросов в секунду (200 000 ÷ 3600), а в пиках — больше. Обработчику, который тратит 300 мс на синхронную работу, нужно около 17 одновременных запросов только для того, чтобы успевать за средним потоком (56 × 0,3); обработчику, который сохраняет строку и отвечает за 20 мс, хватает примерно одного.
@app.post("/hooks/sms")
def sms_hook():
raw = request.get_data() # исходные байты, до любого разбора
if not verify(raw, request.headers.get("X-Meteor-Timestamp", ""),
request.headers.get("X-Meteor-Signature", "")):
return "", 401
inbox_insert(raw) # надёжная запись; дубликаты игнорируются
return "", 200 # всё остальное делает фоновый обработчикОтвечайте 2xx только после того, как событие сохранено. Если база данных недоступна, верните 5xx, и событие придёт снова по графику повторных попыток; не подтверждайте то, что вы потеряли.
Удаляйте дубликаты
Повторные попытки случаются, и каждая из них содержит один и тот же идентификатор события. Храните идентификаторы обработанных событий с уникальным индексом и считайте дубликат успешной обработкой. В этом и состоит вся идемпотентная обработка, и для неё достаточно одной таблицы:
CREATE TABLE webhook_inbox (
event_id text PRIMARY KEY,
payload jsonb NOT NULL,
received_at timestamptz NOT NULL DEFAULT now(),
processed_at timestamptz
);
INSERT INTO webhook_inbox (event_id, payload)
VALUES (:event_id, :payload)
ON CONFLICT (event_id) DO NOTHING;Фоновый обработчик берёт строки с пустым processed_at, применяет их и заполняет это поле — всё в одной транзакции. Повторная отправка из панели тоже сохраняет исходный идентификатор события, поэтому массовая повторная отправка безопасна, даже если часть этих событий уже была получена. Та же идея защищает ваши исходящие вызовы; см. статью о ключе идемпотентности.
Порядок по статусу, а не по времени получения
Порядок доставки не гарантируется, а события, отправленные повторно, по самой своей природе приходят спустя дни. Если сохранять последнее полученное событие, запоздавшее Отправлено отменит Доставлено. Присвойте каждому статусу ранг и двигайтесь только вперёд:
| Статус | Ранг | Чем может быть заменён |
|---|---|---|
| В очереди (queued) | 0 | Отправлено, Доставлено, Ошибка |
| Отправлено (sent) | 1 | Доставлено, Ошибка |
| Доставлено (delivered), Ошибка (failed) | 2 | Ничем: оба статуса окончательные |
UPDATE messages
SET status = :status, status_rank = :rank
WHERE id = :message_id AND status_rank < :rank;Не упорядочивайте события по заголовку X-Meteor-Timestamp: повторно отправленное событие получает новую временную метку и подпись при исходном идентификаторе, поэтому заголовок показывает, когда событие было подписано, а не когда сообщение сменило состояние. В направлениях, которые возвращают только подтверждение оператора связи, Отправлено — окончательный положительный статус, и Доставлено за ним не последует; какой тип подтверждения ожидать, указано на странице каждой страны.
Маршрутизация событий по типу
Исходящие сообщения описываются пятью типами событий: message.sent, message.delivered, message.failed, message.expired и message.rejected; вместе с событиями кампаний и баланса их десять, и каждая конечная точка подписывается только на нужные ей. Если вы арендуете номер с приёмом входящих сообщений, ответы тоже приходят в виде событий. Распределяйте события по типам в фоновом обработчике, а не в обработчике запроса, и отвечайте 2xx на типы, которые пока не обрабатываете, чтобы новый тип сохранялся и игнорировался, а не проходил все шесть попыток доставки.
Два поля исходного сообщения упрощают маршрутизацию. reference — до 128 символов ваших собственных данных — возвращается в вебхуках, поэтому событие находит свой заказ, запись на приём или проверку без таблицы соответствий. webhook_url переопределяет конечную точку для одного сообщения (только HTTPS): так трафик кодов может отчитываться напрямую сервису аутентификации, а трафик кампаний — в аналитику. Событие message.failed содержит понятную причину и исходный код оператора; что делать при каждой причине, объясняет руководство о причинах недоставки SMS.
Повторы, сбои и повторная отправка
Для каждого события выполняется 6 попыток в течение 24 часов: сразу, затем +1 мин, +5 мин, +30 мин, +2 ч и +12 ч. После последней попытки событие помечается как недоставленное. Любой ответ, кроме 2xx в течение 5 секунд, считается неудачной попыткой, включая 401 и 404, поэтому путь обработчика, изменившийся при развёртывании, или секрет, обновлённый в одном месте и забытый в другом, выглядит точно так же, как сбой.
- Развёртывание или кратковременный сбой ничего не стоят: последующие попытки придут, когда вы снова будете доступны.
- Сбой на несколько часов задерживает события, а не теряет их, если последующие попытки приходятся на время после восстановления.
- Сбой на сутки и дольше или неверный секрет, из-за которого на всё приходит ответ 401, исчерпывает все шесть попыток, и события ждут в панели как недоставленные.
Сначала исправьте конечную точку, убедитесь в её работе с помощью повторной отправки одного события, а затем отправьте остальные повторно массово. Повторно отправленные события сохраняют исходный идентификатор события с новой временной меткой и подписью, поэтому проходят пятиминутную проверку, дедупликация поглощает события, которые у вас уже были, а ранжирование статусов обеспечивает правильный порядок. Список недоставленных событий хранится 30 дней; подробнее — в статье о повторной отправке из панели.
Контроль с обеих сторон
На своей стороне настройте оповещения:
- о доле ответов 5xx и доле ответов 401: скачок 401 сразу после развёртывания обычно означает проблему с секретом или разбором тела, а не атаку;
- о задержке обработчика более двух секунд — с большим запасом до лимита в 5 секунд;
- о глубине таблицы входящих событий и возрасте самой старой необработанной строки: они выявляют зависший фоновый обработчик, которого метрики конечной точки никогда не увидят.
В панели для каждой конечной точки показаны доля успешных доставок, последняя ошибка и среднее время ответа, а в списке недоставленных событий для каждого события указан последний код ответа или ошибка. Смотрите на них вместе: падение доли успешных доставок при быстром среднем ответе обычно означает, что конечная точка быстро отвечает неверным кодом статуса.
Смена секрета
Меняйте секрет, когда уходит человек, который его знал, когда секрет мог быть раскрыт, а также по расписанию. После смены секрета в панели старый и новый секреты действуют одновременно 24 часа, поэтому проверка, принимающая список секретов, продолжает работать во время перехода:
- Смените секрет в панели и скопируйте новый.
- Добавьте его в список проверки рядом со старым и разверните изменения.
- Записывайте в журнал, какой секрет совпал; как только события начнут проходить проверку с новым, удалите старый секрет — заведомо до истечения 24 часов.
Храните секрет в хранилище секретов или в переменной окружения, но никогда — в репозитории или журналах.
Проверка перед запуском
Сообщения, отправленные с ключом sk_test_, проходят проверку и расчёт цены так же, как рабочие; ничего не отправляется и не списывается, но вебхуки всё равно срабатывают и подписываются так же, как рабочие. Поэтому весь путь можно проверить бесплатно; см. статью о тестовых ключах. Перед первой реальной кампанией убедитесь, что:
- настоящее событие сохраняется, и ответ на него уходит в течение секунды;
- то же тело с одним изменённым байтом получает 401;
- временная метка десятиминутной давности получает 401;
- одно и то же событие, доставленное дважды, создаёт одну строку;
- Доставлено, за которым следует запоздавшее Отправлено, оставляет статус Доставлено;
- при остановленной базе данных обработчик быстро отвечает 5xx, а не зависает.
Что-то непонятно или устарело? Сообщите нам на странице поддержки. Мы внесём исправления в руководство и обновим дату.
