Вебхуки статуса оплаты счёта

Вебхуки Apiin присылают вашему сервису уведомления о том, что происходит с документом: создан ли счёт, изменился ли статус оплаты, подписан ли акт. Так вы реагируете на события мгновенно и не опрашиваете API в цикле.

Настроить вебхуки Как это работает

Какие события отправляет Apiin

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

На событии оплаты особенно удобно строить автоматику: получили «оплачен» — открыли доступ к услуге; получили «акт подписан» — закрыли сделку. В Apiin для связки счёт↔акт это работает и внутри сервиса через автозакрытие.

Документ создан — счёт, акт или другой документ выпущен
Документ отправлен контрагенту на email
Смена статуса оплаты — частичная или полная оплата
Смена статуса подписи — акт подписан
Сгенерирован повторяющийся счёт по расписанию
Доступ к документу запрошен или выдан

HMAC-подпись и проверка

Каждое уведомление подписывается по HMAC секретом вашей интеграции. Ваш обработчик пересчитывает подпись по телу запроса и сравнивает с присланной: совпало — запрос действительно от Apiin, не совпало — отклоняете. Так вы защищаетесь от поддельных вызовов на ваш публичный URL.

Секрет храните на стороне сервера и никому не передавайте. Формат заголовка с подписью и пример проверки приведены в документации на /docs/api.

Как настроить и обработать вебхук

Укажите в интеграции URL, на который Apiin будет слать события, и подпишитесь на нужные типы. Обработчик должен быстро принять запрос, проверить HMAC-подпись и вернуть успешный ответ; тяжёлую логику выносите в фоновую обработку.

Проектируйте обработчик идемпотентным — одно и то же событие может прийти повторно, и повторная доставка не должна создавать дубли действий на вашей стороне.

Частые вопросы

Какие события можно получать?

Семь событий: создание и отправка документа, смену статусов оплаты и подписи, генерацию повторяющегося счёта, запрос и выдачу доступа к документу. Этого хватает, чтобы синхронизировать вашу систему с Apiin.

Как убедиться, что вебхук пришёл от Apiin?

Проверьте HMAC-подпись: пересчитайте её по телу запроса своим секретом и сравните с присланной. При несовпадении запрос нужно отклонить.

Что делать, если событие пришло дважды?

Сделайте обработчик идемпотентным — реагируйте на событие один раз по его идентификатору. Повторная доставка тогда не создаст дублей.

Можно ли обойтись без вебхуков?

Да, статус оплаты доступен и через REST API запросом. Но вебхуки экономнее: вы получаете событие сразу, без периодического опроса.