События вебхуков

Какие события существуют

Событие	Когда	Для счетов Cashier
payment.succeeded	платёж завершился успешно	да — единственное событие, которое вы получите
refund.succeeded, refund.failed	завершился возврат	нет: возвраты для счетов Cashier недоступны

События refund.* описаны в коде и приходят только тем, кто пользуется возвратами; эта редакция документации их не описывает (формат тела — UNKNOWN для читателя). Игнорируйте незнакомые типы событий: новые типы добавляются без смены версии. Для счетов Cashier нет событий «просрочен» или «не удался» — см. Статусы и поздние платежи.

payment.succeeded

Событие отправляется, когда платёж завершился успешно.

Заголовки

Заголовок	Значение
X-ElevenPay-Signature	t=<unix>,v1=<hex>[,v1=<hex>...] (см. Проверка подписи)
X-ElevenPay-Event-Id	Стабильный идентификатор события (evt_...). Дедуплицируйте по нему.
X-ElevenPay-Event-Type	Тип события (например payment.succeeded)
X-ElevenPay-Delivery-Attempt	Номер попытки доставки
X-ElevenPay-Environment	live или test (справочно; не входит в подпись)
User-Agent	ElevenPay-Webhook/1

Тело события

Каноническое JSON‑тело (именно эти байты подписаны и переданы). Оно не содержит внутренних идентификаторов, id организации, секретов или данных провайдера.

{
  "id": "evt_5wr2a4kqk7m3nd8p9zx6ff0000",
  "type": "payment.succeeded",
  "schema_version": 1,
  "created_at": "2024-09-05T12:00:00Z",
  "data": {
    "payment": {
      "reference": "ep1_7t4k2m8q9x3v6b1n5c0d2f4a8h",
      "merchant_order_id": "order_demo_1001",
      "status": "succeeded",
      "amount": "1500.00",
      "currency": "KZT",
      "created_at": "2024-09-05T11:59:30Z"
    }
  }
}

Поле	Описание
id	Идентификатор события. Совпадает с X-ElevenPay-Event-Id; используйте для дедупликации.
type	payment.succeeded.
schema_version	Версия схемы события (сейчас 1).
created_at	Момент формирования события (UTC).
data.payment	Снимок платежа: reference, merchant_order_id, status, amount, currency, created_at.

Дедупликация по id

Сохраняйте обработанные id событий. Если то же событие пришло повторно — верните 2xx, убедившись, что оно уже обработано, и не выполняйте выдачу повторно. Доставка at‑least‑once, поэтому дубликаты ожидаемы.

То же событие с другим телом

Если приходит событие с уже известным id, но другим телом (иным хэшем содержимого), считайте это аномалией целостности и не выполняйте выдачу повторно. Обрабатывайте как инцидент, а не как обычный дубликат.