Webhook
Требования к реализации ресурса, обрабатывающего webhook
Ожидаем, что на клиенте будет реализована ресурс с POST методом, которая будет отвечать 2xx http кодом. В случае, если получаем 2xx http код, то считаем, что вебхук получен и обработан на стороне клиента.
Ресурс должен быть доступен без какой - либо аутентификации / авторизации, и быть публичным, IP с которых возможна отправка webhook:
- 84.201.153.160
- 158.160.48.198
- 84.201.153.101
- 158.160.170.215
В случае, если при отправки на endpoint будем получать не 2xx ответ, будет совершено 20 попыток отправки данных, с увеличивающимися временным интервалами.
Возможные вариации подписания
Для каждого кабинета в Консоли возможно реализовать (на стороне клиента) один или несколько уникальных эндпоинтов, на которые в дальнейшем подпишем отправку вебхуков (например, один для demo-кабинета, один для боевого);
Для каждого вебхука возможна реализация своего эндпоинта (на стороне клиента), обрабатывающего ту или иную полезную нагрузку, в зависимости, от события, на который хочет подписаться компания. Например, если будет потребность на стороне клиента обрабатывать ивент "Подпись документа" на одном ресурсе, а "Создание задания" иным ресурсом.
Порядок подписания клиентов на вебхук
- На стороне клиента реализован ресурс, обрабатывающий полезную нагрузку от вебхуков, в соответствии с описанием выше и обрабатывающий полезную нагрузку вебхуков / вебхука (для тех ивентов, которые компания хочет получать нотификацию);
- Клиент передает (с учетом тестирования на демо-кабинете): название компании в Консоль.Про, эндоинт(ы), и вебхуки (название), которые компания хочет получать и обрабатывать на своей стороне;
- После тестирования на стороне клиента обработку вебхуков, клиент передает боевой кабинет, эндпоинты и вебхуки, на которые компания хочет получать уведомления.
Общая схема полезной нагрузки в вебхуках
Объект details – полезная нагрузка, отправляемая в вебхуке,в зависимости от типа ивента.
action_cipher – уникальное наименование вебхука (ивента).
Упрощенная полезная нагрузка, отправляемая, в хуке:
Код |
|
Текущие экшены, настроенные на отправку вебхуков
| Cipher | Название | Payload | Описание |
|---|---|---|---|
complete_registration | Исполнитель закончил онбординг | {"details": {"id": 715095, "name": "...", "phone": "...", "status": "waiting_for_contract_sign", "contractor_id": 522863, "custom_fields": {}, "template_fields": {...}}, "manifest": {"action_cipher": "complete_registration"}} | Отправляется в случае, если пользователь ранее не был зарегистрирован на платформе, и проходит регистрацию впервые. Отправляется объект приглашения. Сценарии: пользователь прошел онбординг и Консоль сгенерировала договор; пользователь прошел онбординг и договор не предусмотрен для приглашения (статус будет completed) |
hiring.complete_registration | Дополнительный онбординг завершен исполнителем | {"details": {"id": 715127, "name": "...", "phone": "...", "status": "waiting_for_contract_sign", "contractor_id": 522886, "custom_fields": {}, "template_fields": {}}, "manifest": {"action_cipher": "hiring.complete_registration"}} | Отправляется в случае, если пользователь ранее был зарегистрирован на платформе. Отправляется объект приглашения. Сценарии: пользователь прошел онбординг и Консоль сгенерировала договор; пользователь прошел онбординг и договор не предусмотрен для приглашения (статус будет completed) |
sign_contract | Исполнитель подписал договор | {"details": {"id": 510614, "contractor_id": 261259}, "manifest": {"action_cipher": "sign_contract"}} | Отправляется, когда исполнитель подписывает договор. Поля в payload: id – идентификатор договора; contractor_id – идентификатор исполнителя |
sign_contract_by_all | Завершить подписание договора всеми сторонами | {"details": {"id": 285399, "contractor_id": 173053}, "manifest": {"action_cipher": "sign_contract_by_all"}} | Отправляется, когда договор переходит в финальный статус (подписан всеми необходимыми сторонами). Поля в payload: id – идентификатор договора; contractor_id – идентификатор исполнителя |
workflow.create_tasks | Создать задание | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.create_tasks"}} | Создание нового задания |
workflow.accept_tasks | Принять задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.accept_tasks"}} | Принятие заданий |
workflow.confirm_tasks | Взять задания | {"details": {"id": 50255, "state_code": "confirmed"}, "manifest": {"action_cipher": "workflow.confirm_tasks"}} | Взятие заданий |
workflow.check_in_tasks | Начать работу над заданиями | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.check_in_tasks"}} | Начало работы над заданиями |
workflow.check_in_by_contractor | Исполнитель подтвердил начало задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.check_in_by_contractor"}} | Исполнитель подтвердил начало задания |
workflow.complete_task | Завершить задание | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.complete_task"}} | Завершение задания |
workflow.check_out_by_contractor | Исполнитель подтвердил завершение задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.check_out_by_contractor"}} | Исполнитель подтвердил завершение задания |
workflow.finalize_tasks | Завершение заданий с одновременным созданием актов | {"details": {"id": 50255, "contractor_id": 173053, "state_code": "created"}, "manifest": {"action_cipher": "workflow.finalize_tasks"}} | Завершение заданий с одновременным созданием актов |
workflow.update_task | Обновить задание | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.update_task"}} | Сейчас отключен для всех компаний. Обновление задания. |
workflow.decline_tasks | Отказаться от заданий | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.decline_tasks"}} | Отказ от заданий |
workflow.reject_tasks | Отклонить задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.reject_tasks"}} | Отклонение заданий |
workflow.revoke_tasks | Отозвать задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.revoke_tasks"}} | Отзыв заданий |
workflow.delete_tasks | Удаление заданий | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.delete_tasks"}} | Сейчас отключен для всех компаний. Удаление заданий |
workflow.import_tasks | Импортировать задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.import_tasks"}} | Сейчас отключен для всех компаний. Импорт заданий |
workflow.seed_tasks | Заполнить задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.seed_tasks"}} | Заполнение заданий |
workflow.submit_tasks | Разместить задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.submit_tasks"}} | Размещение заданий |
workflow.auto_confirm_tasks | Принять задание автоматически | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.auto_confirm_tasks"}} | Сейчас отключен для всех компаний. Автоматическое принятие задания |
workflow.confirm_task_reminder_by_contractor | Исполнитель подтвердил выход на задание | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.confirm_task_reminder_by_contractor"}} | Исполнитель подтвердил выход на задание |
workflow.decline_task_reminder_by_contractor | Исполнитель отказался от выхода на задание | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.decline_task_reminder_by_contractor"}} | Исполнитель отказался от выхода на задание |
workflow.ignore_check_in_by_contractor | Исполнитель не подтвердил начало задания | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.update_task"}} | Исполнитель не подтвердил начало задания |
workflow.ignore_task_reminder_by_contractor | Исполнитель проигнорировал задание | {"details": {"id": 50255, "state_code": "created"}, "manifest": {"action_cipher": "workflow.ignore_check_in_by_contractor"}} | Исполнитель проигнорировал задание |
tinkoff.payment_succeeded | Произведена выплата по акту | {"details": {"task_id": 45436}, "manifest": {"action_cipher": "tinkoff.payment_succeeded"}} | Актуально ТОЛЬКО для демо-кабинетов. Поля в payload: task_id – идентификатор акта, по которому произведена выплата |
billing.payment_succeeded | Произведена выплата по акту | {"details": {"task_id": 47582}, "manifest": {"action_cipher": "billing.payment_succeeded"}} | Актуально ТОЛЬКО для боевых кабинетов на номинальных счетах. Поля в payload: task_id – идентификатор акта, по которому произведена выплата |
external_bank.payment_succeeded | Отмечен оплаченым | {"details": {"task_id": 48135}, "manifest": {"action_cipher": "external_bank.payment_succeeded"}} | Клиент платит не через Консоль, а через свое платежное решение. Поля в payload: task_id – идентификатор акта, по которому произведена выплата |
fio_changed | Изменение ФИО исполнителя | {"details": {"user_id": 120399, "last_name": "Логино", "first_name": "Вежи", "patronymic": "Харитонов", "contractor_id": 120737}, "manifest": {"action_cipher": "fio_changed"}} | Отправляется только для заапрувленных поддержкой пользователей. Поля в payload: user_id – идентификатор пользователя; last_name – измененная фамилия пользователя; first_name – измененное имя пользователя; patronymic – измененное отчество пользователя; contractor_id – идентификатор исполнителя |
mobile_phone_changed | Изменение номера телефона исполнителя | {"details": {"user_id": 120399, "mobile_phone": "+70002977728", "contractor_id": 120737}, "manifest": {"action_cipher": "mobile_phone_changed"}} | Отправляется только для заапрувленных поддержкой пользователей. Поля в payload: user_id – идентификатор пользователя; mobile_phone – измененный номер телефона исполнителя; contractor_id – идентификатор исполнителя |