Вебхуки: обзор и настройка

Eleven Pay отправляет подписанные HTTP‑POST уведомления на ваш сервер, когда платёж завершается успешно. Вебхуки и GET‑сверка дополняют друг друга.

Настройка endpoint

В кабинете мерчанта app.eleven.kz → Вебхуки укажите HTTPS‑адрес вашего обработчика. Поддерживается один включённый endpoint. При настройке вы получите секретный ключ подписи — он показывается один раз, сохраните его на сервере.

Требования к адресу

Адрес проверяется при сохранении. Он должен быть:

• HTTPS (обязательно);
• с указанным хостом (доменом);
• без учётных данных в URL (user:pass@);
• без строки запроса (?...);
• без фрагмента (#...);
• не IP‑адрес‑литерал (используйте доменное имя);
• стандартный порт HTTPS.

Адреса назначения дополнительно проверяются на стороне Eleven Pay для защиты от SSRF.

Что доставляется

• События: payment.succeeded (для счетов Cashier — единственное; см. События).
• Заголовки: X-ElevenPay-Signature, X-ElevenPay-Event-Id, X-ElevenPay-Event-Type, X-ElevenPay-Delivery-Attempt, User-Agent: ElevenPay-Webhook/1.
• Тело: канонический JSON‑снимок события (подписанные сырые байты).

Обязательные шаги обработки

1. Проверьте подпись по точным сырым байтам тела — Проверка подписи.
2. Дедуплицируйте по X-ElevenPay-Event-Id — доставка at‑least‑once.
3. Идемпотентно выдайте товар/услугу после проверки заказа/суммы — Идемпотентная обработка.
4. Верните 2xx только после надёжной обработки.

Готовый пример обработчика — Обработчик вебхуков.

Ответ вашего сервера

2xx останавливает повторы; 5xx и сетевые ошибки приводят к повтору; прочие 4xx считаются терминальными (см. Доставка и повторы). Возвращайте 2xx только после того, как обработка надёжно зафиксирована. Тело ответа не требуется — важен только статус; не возвращайте секреты или отладочные данные.

Перенаправления не выполняются

Доставка вебхука не следует за редиректами (3xx). Ваш endpoint должен возвращать финальный ответ напрямую.