Вебхуки (обратный вызов)

Вебхуки (webhooks) — это запросы, отправляемые Планадо на ваш сервер в момент, когда в Планадо происходят изменения данных. Например, когда начинается или завершается наряд, обновляется клиент и т.д.

Вебхуки поддерживаются только для нарядов, клиентов и объектов.

Технически вебхук это HTTP POST-запрос от сервера Планадо к вашему серверу, указанному в настройках API. Тело этого запроса содержит информацию о событии в Планадо в формате JSON.

Надежность доставки

Вебхук считается успешно доставленным, если принимающий сервер ответил кодом 2xx.

Если сервер ответил неуспехом или был недоступен, Планадо будет повторять попытки доставки еще 17 раз с увеличивающимся интервалом между запросами. Последняя попытка будет сделана примерно через неделю после первой.

Каждый запрос содержит заголовок X-Planado-Delivery-Attempt, содержащий номер попытки, начиная с единицы.

Время обработки вебхука ограничено 10 секундами. Если ваш сервер не успевает обработать запрос за это время, запрос будет считаться неуспешным.
Мы рассчитываем, что большинство вебхуков будет обработано в среднем с первой попытки. Большое количество отказов в обработке со стороны вашего сервера может привести к отключению вебхуков. В этом случае вам нужно будет устранить проблему в обработке, а потом написать нам в поддержку для возобновления доставки.

Версии и порядок доставки

Сущности Планадо, для которых доступны вебхуки, имеет внутренний номер версий. Версия — это целое число, начиная с единицы, которое обозначает ревизию сущности. Каждое изменение увеличивет номер версии, строго по порядку. Этот порядок, однако, может не соблюдаться запросами вебхуков. Рассмотрим следующий случай:

  • Происходит изменение А в наряде №42. API отправляет запрос с изменением, но запрос не доходит до получателя из-за временной сетевой ошибки.

  • Происходит изменение Б в том же наряде. В этот раз вебхук успешно срабатывает, запрос обрабатывается сервером.

  • Наконец, запрос по изменению А повторяется и тоже успешно доставляется.

С точки зрения вашего сервера это будет означать, что изменение Б произошло до изменения А. В зависимости от ситуации и требований это может привести к неконсистентному состоянию. Для того, чтобы предоставить возможность гарантировать порядок получения сообщений, тело вебхука содержит поле version — версию сущности, которой соответствует изменение.

Вы можете сохранить значение version в своей системе. После этого у вас будет две основных стратегии для обеспечения порядка обработки.

Последняя версия имеет приоритет (last write wins)

Требования: требуется хранить только самое последнее состояние, игнорируя все запросы, нарушающие порядок.

  • Когда приходит запрос, сравните его версию y с сохраненной прежде версией x.

  • Если y > x, то запрос — обычное обновление по порядку. Обработайте его и обновите сохраненную версию x на y.

  • Если y < x, то запрос сделан не по порядку, это пропущенное ранее обновление. Игнорируйте запрос, ответив кодом 200, чтобы Планадо не повторяло попытки доставки.

Полная репликация

Требования: состояние должно быть полностью реплицировано, все обновления должны быть обработаны в порядке их возникновения в Планадо.

  • Когда приходит запрос, сравните его версию y с сохраненной прежде версией x.

  • Если y == x + 1, это последовательное обновление. Обработайте запрос и обновите версию сохраненную версию x на y.

  • Если y != x + 1, это запрос не по порядку. Ответьте Планадо любым кодом >= 400 (например, 422) и ожидайте пропущенное обновление. Планадо повторит доставку позже.

В случает полной репликции одно пропущенное обновление может привести к задержкам в синхронизации конкретной сущности.

Аутентификация отправителя

Для аутентификации Планадо как отправителя вы можете в настройках вебхуков в Планадо задать строку, которая будет отправляться в заголовке запроса X-Planado-Secret.

Структура запроса

Тело вебхука это JSON-объект с тремя полями:

  • event_type — тип изменения, строка. Пример: "job_created", "client_updated" или "site_removed".

  • context содержит временные метки и информацию об авторе изменения.

  • job, client или site это подробная информация с состоянием сущности. Подробный формат описан в документации на вебхуки для конкретного ресурса (например, CRUD-вебхуки нарядов).

Формат контекста

Поле Тип JSON-тип Может быть null Описание

source

UUID

Строка

Нет

Уникальный идентификатор

happened_at

Дата и время

Строка

Нет

Время изменения

created_at

Дата и время

Строка

Нет

Время изменения сервером. Для событий, произошедших в мобильном приложении, это значение обычно будет в будущем отноcительно happened_at

user_uuid

UUID

Строка

Да

Идентификатор автора изменения

user_email

Строка

Строка

Да

Email автора изменения

device_uuid

UUID

Строка

Да

Идентификатор устройства

Временные токены для доступа к API

Каждый вебхук-запрос содержит заголовок X-Planado-Api-Token, в котором хранится временный токен для доступа к API. Токен — это короткоживущий ключ, который может быть использован вместо постоянного API-ключа. Это подходит для случаев, когда в ответ на вебхук-запрос нужно обратиться в API Планадо. Правила аутентификации для токенов такие же, как и для постоянных ключей: передается в заголовке Authorization с префиксом `Bearer `. Каждый токен можно использовать только в течение 1 минуты с начала вебхук-запроса.