---
title: Безопасность
description: Как проверять и защищать полезные данные вебхуков IDCloud — верификация подписи и лучшие практики.
canonical: https://developer.unico.io/ru/dual-api/developers/webhooks-and-events/security
locale: ru
generated_by: markdown-export
---

Надёжность вебхуков зависит как от поведения вашего эндпоинта, так и от гарантий доставки со стороны Unico. На этой странице описаны три инварианта, которым должен соответствовать ваш эндпоинт: **идемпотентность**, **ограничение параллелизма** и **частота ошибок**.

### Идемпотентность

Реализация вебхуков Unico гарантирует **доставку хотя бы один раз** — один и тот же статус может быть отправлен более одного раза для одного и того же `processId`. Ваш эндпоинт **должен** быть идемпотентным.

Рекомендуемый паттерн:

1. При каждом вызове вебхука сначала проверьте, был ли `processId` уже обработан.
2. Если да — немедленно верните `2xx` (работа уже выполнена).
3. Если нет — примените бизнес-логику и сохраните информацию о том, что этот `processId` был обработан.

```javascript
// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}
```

:::warning[Почему это важно]
Неидемпотентный эндпоинт, выполняющий бизнес-логику при каждой доставке (например, списывающий деньги с карты или отправляющий email), будет срабатывать повторно при каждой повторной попытке — а повторные попытки являются нормой, а не исключением при доставке вебхуков.
:::

### Ограничение параллелизма

Чтобы защитить ваш эндпоинт от всплесков нагрузки в периоды высокой активности, при регистрации вебхука задайте максимальное количество одновременных активных доставок (максимум: **500**).

При достижении лимита параллелизма Unico ставит дополнительные доставки в очередь и обрабатывает их по мере освобождения ресурсов. В сочетании с механизмом повторных попыток это означает, что продолжительный всплеск может увеличить фактическое время доставки новых вебхуков.

### Частота ошибок

Частота ошибок (ответы вне диапазона `200`–`299`) должна всегда оставаться низкой. Если ваш эндпоинт начинает возвращать ошибки в масштабе, Unico **автоматически снижает пропускную способность вебхуков** для этого эндпоинта. В сочетании с механизмом повторных попыток это может значительно увеличить время выполнения новых вебхуков.

Операционные рекомендации:

- Отслеживайте ответы не-2xx на своей стороне. Настройте оповещения при устойчивом превышении нормального уровня ошибок.
- Относитесь к обработчику вебхуков как к **критическому пути** — он должен быть одним из наиболее надёжных сервисов в вашем стеке.
- **При плановом техническом обслуживании** предпочтительнее останавливать приём трафика на уровне балансировщика нагрузки, а не возвращать `503`. Устойчивые ответы не-2xx — включая `503` — активируют автоматическое снижение пропускной способности, описанное выше; когда ваш эндпоинт восстановится, сниженная пропускная способность задержит доставку событий, накопившихся во время простоя. Не возвращайте `200` для необработанных событий.

### Семантика статусов

Воспринимайте набор значений `state` и `lastEvent` как развивающуюся конфигурацию:

- Реагируйте только на состояния / события, которые вы явно обрабатываете.
- Логируйте неизвестные значения — не генерируйте ошибки при их получении.
- Новые состояния могут быть добавлены без изменения мажорной версии.