ProtoPays · API
кабинет

webhooks

При смене статуса внешнего платежа сервис отправляет HTTP POST на URL из заявки (callbackUri). Пример тела JSON и поля — в разделе Webhook по платежу. По выплатам исходящий webhook в том же виде пока не реализован — см. Webhook по выплатам.

дубликаты, порядок и идемпотентность

  • Дубликаты возможны. Одно и то же событие или близкое по смыслу уведомление может быть доставлено более одного раза (повторы после сбоев, повторная постановка в очередь).
  • Порядок доставки не гарантируется. Более позднее по времени событие может прийти раньше более раннего; не полагайтесь на порядок HTTP-запросов к вашему endpoint.
  • Обработчик обязан быть идемпотентным. Повторная обработка того же uuid / id платежа не должна менять ваше состояние дважды (используйте атомарное подтверждение или хранение последней обработанной версии).

Входящая идемпотентность по HTTP-заголовкам на стороне API описана в разделе идемпотентность — к исходящим webhook это не относится.

успешная доставка

Доставка считается успешной, если ваш endpoint ответил HTTP-кодом из диапазона 2xx. Любой другой код или обрыв соединения — неуспех; возможны повторы по политике ниже.

тайминги HTTP

  • Таймаут установления соединения: 10 с.
  • Общий таймаут ответа: 25 с.

Ответьте 2xx быстро; тяжёлую работу выполняйте асинхронно у себя.

политика повторов (retry)

  1. До 3 попыток подряд с задержками 60 с и 300 с между попытками.
  2. Дополнительно раз в 5 минут переотправка для недоставленных callback, пока число зафиксированных попыток меньше 10.

Из-за повторов дубликаты неизбежны в принципе — см. блок выше.

рекомендации по приёму

  • Проверяйте подпись / секрет, если он предусмотрен спецификацией.
  • Ведите учёт обработанных uuid / id.