Все заметки
Программирование

Не верьте вебхуку на слово: 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")

Ошибок здесь не одна, а шесть:

  1. sha256(secret + message) — это не HMAC. Для хешей на конструкции Меркла — Дамгора, вроде SHA-256, такая схема уязвима к length extension. Именно поэтому для подписей существует модуль hmac.
  2. json.dumps(json.loads(body)) не возвращает исходные байты: пробелы, порядок ключей, unicode-экранирование отличаются. Провайдер подписал сырые байты, и проверять нужно сырые байты.
  3. Сравнение через != останавливается на первом несовпавшем символе. Теоретически это утечка через время ответа; hmac.compare_digest работает за постоянное время.
  4. Нет timestamp. Перехваченный однажды настоящий запрос (с правильной подписью!) можно переотправить когда угодно — это replay-атака.
  5. Нет проверки дубликатов по id события, так что при ретрае провайдера всё выполняется заново.
  6. Тяжёлая работа (письмо, 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, может прийти к вам первым. Если обработчик считает последнее пришедшее событие «самым свежим состоянием», состояние откатывается назад.

Есть два надёжных подхода:

  1. Условное обновление по версии или времени. Храним на объекте время последнего применённого события и применяем только более новые.
  2. «Тонкое» событие + перечитывание. Событие — просто сигнал «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 отвечают на вопрос, кто отправил; уникальное ограничение — сколько раз обработано; условное обновление — какое состояние последнее. Пусть эндпоинт только принимает, а работу делает очередь — тогда ретраи становятся не угрозой, а просто шумом.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯