Обзор

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, и подпись останется действительной, пока метка времени проходит вашу проверку. Обработчик, который сверяет заголовок, примет такую копию второй раз.

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

• Каталог событий — все события инвойсов, выводов и платёжных каналов
• Контракт тела события — общая оболочка события и снимки ресурсов
• Проверка подписи — HMAC по исходному телу и ротация секрета
• Доставка и повторы — таймаут, задержки, идемпотентность и переотправка
• Тестирование вебхуков — требования тестового режима и интерактивная песочница