# Вебхуки

> Подключите Paymos к своему серверу через подписанные адреса вебхуков с разделением по окружениям и полным контролем доставки.

Paymos отправляет HTTPS `POST`, когда меняется состояние инвойса, вывода или депозита платёжного канала. Вебхуки — основной асинхронный сигнал для вашего сервера: API-ответ запускает операцию, а событие вебхука сообщает результат после обработки в блокчейне.

## Схема интеграции

1. Создайте адрес вебхука в **Дашборд → Разработчик → Вебхуки**.
2. Выберите одну или несколько категорий событий: «Инвойсы», «Выводы», «Платёжные каналы».
3. При необходимости ограничьте события инвойсов и платёжных каналов выбранными проектами — фильтр у них общий. События выводов действуют на весь аккаунт мерчанта, фильтр на них не влияет.
4. Сохраните показанный секрет `whsec_…` на сервере.
5. Проверяйте каждую доставку по неизменённому исходному телу запроса.
6. Сохраняйте `event_id`, отвечайте `2xx` и обрабатывайте событие асинхронно.

У рабочего и тестового режима отдельные адреса, секреты и события. Тестовое событие никогда не доставляется на рабочий адрес.

## Правила адресов

- URL должен использовать HTTPS.
- В URL допустим порт 443 — он же действует, когда порт не указан, — или любой порт от 1024 и выше. Другие порты отклоняются при сохранении, а на адрес, где такой порт уже указан, доставки не идут.
- Для одного мерчанта можно настроить до 10 адресов на окружение.
- Один активный URL нельзя зарегистрировать дважды в одном окружении.
- У адреса должна быть хотя бы одна категория событий.
- Без фильтра проектов на адрес приходят события всех проектов.
- Приостановка или удаление адреса прекращает новые доставки на него.

## Заголовки доставки

| Заголовок | Контракт |
|-----------|----------|
| `Content-Type` | `application/json; charset=utf-8` |
| `X-Webhook-Id` | То же значение `evt_…`, что `event_id` в теле; в подпись не входит |
| `X-Webhook-Timestamp` | Unix-время этой попытки доставки в секундах |
| `X-Webhook-Signature` | `t={timestamp},v1={hmac_hex}`; при ротации может содержать два значения `v1` |

Доставка идёт не реже одного раза, а порядок не гарантируется. Сначала проверьте подпись, затем дедуплицируйте по `event_id` из тела и применяйте состояние ресурса из `data` — не считайте количество событий и не полагайтесь на порядок прихода.

`X-Webhook-Id` нужен для журналов, а не для дедупликации. В подпись входят только метка времени и тело, поэтому перехваченную доставку можно отправить заново с другим `X-Webhook-Id`, и подпись останется действительной, пока метка времени проходит вашу проверку. Обработчик, который сверяет заголовок, примет такую копию второй раз.

## Документация вебхуков

- [Каталог событий](/ru/docs/webhooks/events.md) — все события инвойсов, выводов и платёжных каналов
- [Контракт тела события](/ru/docs/webhooks/payloads.md) — общая оболочка события и снимки ресурсов
- [Проверка подписи](/ru/docs/webhooks/verify.md) — HMAC по исходному телу и ротация секрета
- [Доставка и повторы](/ru/docs/webhooks/retry.md) — таймаут, задержки, идемпотентность и переотправка
- [Тестирование вебхуков](/ru/docs/webhooks/testing.md) — требования тестового режима и интерактивная песочница