Не верьте вебхуку на слово: HMAC-подпись, защита от replay, дубликаты и очередь
Провайдер присылает одно событие три раза, иногда не в том порядке, а иногда его присылает вовсе не провайдер. Разбираем по шагам, как принимать вебхуки в Django и Celery безопасно и ровно один раз по эффекту.
Представьте: платёжный провайдер отправляет на ваш /webhooks/acme/ событие payment.succeeded. Обработчик обновляет заказ, генерирует PDF-чек и отправляет письмо. Это занимает несколько секунд, а таймаут у провайдера короче. Ответа нет — значит, «не доставлено», и через минуту провайдер шлёт то же событие ещё раз. Клиент получает два чека, в истории заказа две записи.
Тем временем кто-то нашёл URL эндпоинта в логах и вручную отправил {"type": "payment.succeeded", "order_id": 777}. Если проверка подписи слабая, заказ становится «оплаченным». И третья проблема: для подписки почти одновременно ушли subscription.canceled и subscription.updated, но второе пришло первым, и отменённая подписка снова стала active.
Эти три проблемы — поддельные запросы, повторная доставка и нарушенный порядок — следуют из самой природы вебхуков. Отмахнуться «это редкость» не выйдет: почти все провайдеры прямо обещают доставку at-least-once (хотя бы один раз), а не exactly-once. В статье соберём принимающую сторону целиком, а в конце посмотрим, что нужно делать, если вебхуки отправляете вы сами.
Почему наивный обработчик ломается
Первая версия во многих проектах выглядит примерно так:
# webhooks/views.py -- DON'T do this
import hashlib
import json
from django.conf import settings
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from orders.models import Order
from orders.emails import send_receipt_email
@csrf_exempt
def acme_webhook(request):
data = json.loads(request.body)
expected = hashlib.sha256(
(settings.ACME_SECRET + json.dumps(data)).encode()
).hexdigest()
if expected != request.headers.get("X-Webhook-Signature"):
return HttpResponse(status=401)
order = Order.objects.get(pk=data["data"]["order_id"])
order.status = data["data"]["status"]
order.save()
send_receipt_email(order) # SMTP, PDF, a few seconds
return HttpResponse("ok")
Ошибок здесь не одна, а шесть:
sha256(secret + message)— это не HMAC. Для хешей на конструкции Меркла — Дамгора, вроде SHA-256, такая схема уязвима к length extension. Именно поэтому для подписей существует модульhmac.json.dumps(json.loads(body))не возвращает исходные байты: пробелы, порядок ключей, unicode-экранирование отличаются. Провайдер подписал сырые байты, и проверять нужно сырые байты.- Сравнение через
!=останавливается на первом несовпавшем символе. Теоретически это утечка через время ответа;hmac.compare_digestработает за постоянное время. - Нет timestamp. Перехваченный однажды настоящий запрос (с правильной подписью!) можно переотправить когда угодно — это replay-атака.
- Нет проверки дубликатов по id события, так что при ретрае провайдера всё выполняется заново.
- Тяжёлая работа (письмо, PDF) внутри запроса. Ответ тормозит, случается таймаут, приходит ретрай — то есть пункт 5 «включается» именно отсюда.
Шаг 1: подпись и timestamp
Надёжная схема такая: у вас с провайдером общий secret. Провайдер подписывает строку timestamp.body через HMAC-SHA256 и присылает два заголовка: X-Webhook-Timestamp и X-Webhook-Signature. Вы повторяете вычисление и сравниваете результат за постоянное время. Timestamp входит в подпись, поэтому подменить его нельзя, а старый запрос выпадает из окна и отклоняется.
# webhooks/signing.py
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 300
class SignatureError(Exception):
pass
def compute_signature(secret: bytes, timestamp: str, body: bytes) -> str:
signed_payload = timestamp.encode() + b"." + body
return hmac.new(secret, signed_payload, hashlib.sha256).hexdigest()
def verify_signature(
secrets: list[bytes],
timestamp: str | None,
signature: str | None,
body: bytes,
) -> None:
if not timestamp or not signature:
raise SignatureError("missing headers")
try:
ts = int(timestamp)
except ValueError:
raise SignatureError("bad timestamp") from None
if abs(time.time() - ts) > TOLERANCE_SECONDS:
raise SignatureError("timestamp outside tolerance")
# Several secrets = rotation without downtime (old + new).
for secret in secrets:
expected = compute_signature(secret, timestamp, body)
if hmac.compare_digest(expected, signature):
return
raise SignatureError("signature mismatch")
Список секретов нужен для ротации. Добавляете новый секрет, меняете его в панели провайдера, через какое-то время убираете старый. Никакого «окна простоя».
# settings.py
import os
ACME_WEBHOOK_SECRETS = [
s.encode() for s in os.environ["ACME_WEBHOOK_SECRETS"].split(",") if s
]
Имена заголовков и формат подписи зависят от провайдера: кто-то использует hex, кто-то base64, кто-то кладёт в заголовок несколько значений вида t=...,v1=.... Механизм почти всегда один: HMAC, сырое тело, timestamp. Если в официальном SDK провайдера есть функция проверки — используйте её.
Подпись говорит «этот запрос отправил владелец секрета». Она не говорит «этот запрос пришёл впервые». Поэтому окно по timestamp и дедупликация по id события — разные вещи, и нужны обе.
Пятиминутное окно не убивает replay полностью: перехваченный запрос можно повторить внутри окна. Это закрывает следующий шаг — фильтр дубликатов.
Шаг 2: быстрый 200, работа — в очередь
У принимающего эндпоинта одна задача: проверить, сохранить, сказать «принято». Бизнес-логика — в Celery-воркере. Сначала пишем событие в базу:
# webhooks/models.py
from django.db import models
class WebhookEvent(models.Model):
class Status(models.TextChoices):
PENDING = "pending"
PROCESSED = "processed"
FAILED = "failed"
provider = models.CharField(max_length=32)
event_id = models.CharField(max_length=128)
event_type = models.CharField(max_length=64)
payload = models.JSONField()
status = models.CharField(
max_length=16, choices=Status, default=Status.PENDING
)
received_at = models.DateTimeField(auto_now_add=True)
processed_at = models.DateTimeField(null=True, blank=True)
class Meta:
constraints = [
models.UniqueConstraint(
fields=["provider", "event_id"], name="uniq_webhook_event"
),
]
indexes = [models.Index(fields=["status", "received_at"])]
UniqueConstraint(provider, event_id) — основа дедупликации. Проверка не в коде, а в PostgreSQL: даже если два параллельных запроса пришли с одним событием, уникальный индекс пропустит INSERT только одного из них.
# webhooks/views.py
import json
from django.conf import settings
from django.db import transaction
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from .models import WebhookEvent
from .signing import SignatureError, verify_signature
from .tasks import process_webhook_event
@csrf_exempt
@require_POST
def acme_webhook(request):
body = request.body # raw bytes, exactly what was signed
try:
verify_signature(
settings.ACME_WEBHOOK_SECRETS,
request.headers.get("X-Webhook-Timestamp"),
request.headers.get("X-Webhook-Signature"),
body,
)
except SignatureError:
return HttpResponse(status=400)
try:
payload = json.loads(body)
event_id = str(payload["id"])
event_type = str(payload["type"])
except (ValueError, KeyError, TypeError):
return HttpResponse(status=400)
with transaction.atomic():
event, created = WebhookEvent.objects.get_or_create(
provider="acme",
event_id=event_id,
defaults={"event_type": event_type, "payload": payload},
)
if created:
transaction.on_commit(
lambda: process_webhook_event.delay(event.pk)
)
# Duplicate or new: the answer is the same, 200.
return HttpResponse(status=200)
Несколько важных деталей:
get_or_createвместе с уникальным ограничением безопасен при гонке: второй запрос получаетIntegrityErrorна INSERT, Django перехватывает его и возвращает существующую строку (created=False).- Задача ставится через
transaction.on_commit. Если вызвать.delay()напрямую, воркер может стартовать раньше коммита и не найти строку. - На дубликат тоже отвечаем 200. Если вернуть 409 или 500, провайдер сочтёт доставку неудачной и продолжит ретраи.
- При неверной подписи не объясняем причину в ответе — хватит 400. Причину пишем в свой лог.
Шаг 3: воркер обязан быть идемпотентным
Дедупликация в эндпоинте решает только задачу «одно событие не сохранится дважды». Но и сам Celery может выполнить задачу дважды (acks_late, падение воркера, visibility timeout). Поэтому воркер тоже блокирует строку и проверяет статус:
# webhooks/tasks.py
from datetime import timedelta
from celery import shared_task
from django.db import transaction
from django.utils import timezone
from .handlers import handle_event
from .models import WebhookEvent
@shared_task(acks_late=True)
def process_webhook_event(event_pk: int) -> None:
with transaction.atomic():
event = (
WebhookEvent.objects.select_for_update()
.filter(pk=event_pk)
.first()
)
if event is None or event.status == WebhookEvent.Status.PROCESSED:
return
handle_event(event) # DB work only, no HTTP calls under the lock
event.status = WebhookEvent.Status.PROCESSED
event.processed_at = timezone.now()
event.save(update_fields=["status", "processed_at"])
@shared_task
def requeue_stale_webhook_events() -> None:
# Safety net: broker was down when on_commit fired, worker died, etc.
cutoff = timezone.now() - timedelta(minutes=10)
stale = WebhookEvent.objects.filter(
status=WebhookEvent.Status.PENDING, received_at__lt=cutoff
).values_list("pk", flat=True)[:500]
for pk in stale:
process_webhook_event.delay(pk)
select_for_update() заставляет второй параллельный воркер ждать коммита первого; затем второй видит PROCESSED и выходит. Условие: внутри handle_event не должно быть внешних HTTP-вызовов — ожидание сети под блокировкой держит соединение и блокирует другие запросы. Нужны письмо или внешний API — выносите их в отдельную задачу, снова через on_commit.
requeue_stale_webhook_events — страховочная сетка. Если .delay() внутри on_commit попал на момент, когда брокер недоступен, событие останется в базе в статусе pending, и никто его не заберёт. Эта задача, запускаемая через Celery beat раз в несколько минут, переставляет такие «осиротевшие» события в очередь. Воркер идемпотентен, так что лишняя постановка не вредит.
Шаг 4: события приходят не по порядку
Провайдер отправляет события из разных воркеров, с ретраями, параллельно. canceled, созданное после updated, может прийти к вам первым. Если обработчик считает последнее пришедшее событие «самым свежим состоянием», состояние откатывается назад.
Есть два надёжных подхода:
- Условное обновление по версии или времени. Храним на объекте время последнего применённого события и применяем только более новые.
- «Тонкое» событие + перечитывание. Событие — просто сигнал «
sub_42изменился». Дальше вы берёте текущее состояние объекта из API провайдера. Проблема порядка исчезает, но на каждое событие добавляется один вызов API.
Первый подход в коде:
# webhooks/handlers.py
from datetime import datetime, timezone as dt_timezone
from django.db.models import Q
from billing.models import Subscription
def handle_event(event) -> None:
if event.event_type != "subscription.updated":
return # unknown types: store, acknowledge, ignore
data = event.payload["data"]
occurred_at = datetime.fromtimestamp(
event.payload["created"], tz=dt_timezone.utc
)
# Conditional UPDATE: an older event can never overwrite a newer state.
Subscription.objects.filter(
external_id=data["subscription_id"],
).filter(
Q(last_event_at__isnull=True) | Q(last_event_at__lt=occurred_at)
).update(
status=data["status"],
last_event_at=occurred_at,
)
Это превращается в один атомарный SQL — между чтением и записью нет гонки:
UPDATE billing_subscription
SET status = 'canceled', last_event_at = '2026-11-20 10:00:05+00'
WHERE external_id = 'sub_42'
AND (last_event_at IS NULL OR last_event_at < '2026-11-20 10:00:05+00');
Осторожно: если два события созданы в одну и ту же секунду, < отбросит второе. Если провайдер отдаёт sequence или версию объекта, используйте её вместо времени. Если такого поля нет, а состояние критично (платёж, подписка), второй подход надёжнее.
Сторона отправителя: ретраи, backoff, jitter
Если вебхуки отправляете вы, роли меняются: теперь вы обещаете at-least-once и создаёте условия, чтобы получатель мог сделать всё описанное выше. Основные правила:
- Id события одинаков во всех попытках, а timestamp и подпись считаются заново на каждую (иначе ретрай через час не пройдёт пятиминутное окно получателя).
- Ретраи с экспоненциальным backoff и jitter, чтобы сотни клиентов, упавших одновременно, не получили повторный удар в одну и ту же секунду.
- 2xx — успех. 5xx, 408, 429 и сетевые ошибки — ретрай. Остальные 4xx не ретраим, но логируем.
- Всегда таймаут. У
requestsнет таймаута по умолчанию, он может ждать вечно. - Задачу отправки создавайте в одной транзакции с бизнес-операцией (outbox или
on_commit), иначе событие потеряется.
# outgoing/tasks.py
import json
import time
import requests
from celery import shared_task
from django.utils import timezone
from webhooks.signing import compute_signature
from .models import WebhookDelivery
class RetryableDeliveryError(Exception):
pass
@shared_task(
autoretry_for=(
RetryableDeliveryError,
requests.ConnectionError,
requests.Timeout,
),
retry_backoff=5, # 5s, 10s, 20s, 40s ...
retry_backoff_max=3600, # never wait more than an hour
retry_jitter=True, # spread retries, avoid a thundering herd
max_retries=12,
acks_late=True,
)
def deliver_webhook(delivery_id: int) -> None:
delivery = WebhookDelivery.objects.select_related("endpoint").get(
pk=delivery_id
)
if delivery.delivered_at is not None:
return
body = json.dumps(
delivery.payload, separators=(",", ":"), ensure_ascii=False
).encode()
ts = str(int(time.time())) # fresh timestamp on every attempt
signature = compute_signature(
delivery.endpoint.secret.encode(), ts, body
)
resp = requests.post(
delivery.endpoint.url,
data=body,
headers={
"Content-Type": "application/json",
"X-Webhook-Id": str(delivery.event_id), # same on every retry
"X-Webhook-Timestamp": ts,
"X-Webhook-Signature": signature,
},
timeout=(3, 10),
allow_redirects=False,
)
delivery.last_status = resp.status_code
if 200 <= resp.status_code < 300:
delivery.delivered_at = timezone.now()
delivery.save(update_fields=["last_status", "delivered_at"])
return
delivery.save(update_fields=["last_status"])
if resp.status_code in (408, 429) or resp.status_code >= 500:
raise RetryableDeliveryError(f"HTTP {resp.status_code}")
# Other 4xx: the receiver rejected the request; retrying won't help.
В Celery retry_backoff=5 даёт задержки 5, 10, 20, 40... секунд, retry_backoff_max их ограничивает, а retry_jitter=True выбирает каждую задержку случайно в диапазоне от 0 до вычисленного значения. Когда max_retries исчерпан, Celery пробрасывает последнее исключение — в этот момент полезно пометить доставку как failed, показать её клиенту в дашборде и дать кнопку ручной переотправки. Если клиенты сами вводят URL, allow_redirects=False и блокировка внутренних IP защищают от SSRF.
Локальная проверка
Эндпоинт можно проверить и без песочницы провайдера — подпись считаем через openssl:
SECRET='whsec_test'
BODY='{"id":"evt_1","type":"ping","created":1763632800,"data":{}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
curl -sS -i -X POST http://localhost:8000/webhooks/acme/ \
-H 'Content-Type: application/json' \
-H "X-Webhook-Timestamp: $TS" \
-H "X-Webhook-Signature: $SIG" \
--data-binary "$BODY"
Отправьте ту же команду дважды: второй раз тоже должен вернуться 200, но в базе — одна строка и одна выполненная задача. Подставьте в TS значение десятиминутной давности — должны получить 400.
Подводные камни в продакшене
| Проблема | Симптом | Решение |
|---|---|---|
| Тело изменено по пути | Подпись никогда не сходится | Проверяйте только request.body, middleware не должен переписывать тело |
| Уплыли часы сервера | Все события «старые» | NTP, не делайте окно слишком узким |
| Большой payload | RequestDataTooBig, 400 |
DATA_UPLOAD_MAX_MEMORY_SIZE действует и на request.body |
| Брокер недоступен | Событие застряло в pending |
Периодическая задача requeue |
| Таблица растёт бесконечно | Медленные запросы | Чистка старых processed или партиционирование |
И ещё:
- Ключ дедупликации — id события провайдера, а не хеш payload. Некоторые провайдеры добавляют в payload номер попытки, и хеш меняется.
- На неизвестные типы событий тоже отвечайте 200 и сохраняйте их. Когда провайдер добавит новый тип, эндпоинт не должен превратиться в шторм ретраев.
- Не логируйте секрет, а вот ошибки подписи логируйте — это первый признак атаки или кривой конфигурации.
- IP allowlist не заменяет подпись; это максимум дополнительный слой.
csrf_exempt— только на view вебхука. Не отключайте CSRF для целого URL-префикса.
Чеклист
- HMAC-SHA256, сырой
request.body,hmac.compare_digest. - Timestamp внутри подписи, окно ±5 минут.
- Несколько секретов для ротации.
UniqueConstraint(provider, event_id)+get_or_create.- Сохранить, поставить в очередь через
on_commit, сразу 200 (и на дубликат тоже). - В воркере
select_for_update+ проверка статуса, без HTTP под блокировкой. - Периодический requeue для застрявших в
pending. - Для порядка — условный
UPDATEили перечитывание из API. - Если отправляете сами: стабильный id события, свежая подпись, backoff + jitter, таймаут, ручная переотправка.
Итог
Вебхук — это не «команда, которая придёт один раз», а «сообщение, которое придёт хотя бы раз, в любом порядке и, возможно, поддельным». Подпись и timestamp отвечают на вопрос, кто отправил; уникальное ограничение — сколько раз обработано; условное обновление — какое состояние последнее. Пусть эндпоинт только принимает, а работу делает очередь — тогда ретраи становятся не угрозой, а просто шумом.
// комментарии
Загружаем комментарии...