Настройка вебхуков для реальных обновлений Sign.Plus

Веб-хуки позволяют получать в режиме реального времени новости о состоянии ваших конвертов в Sign.Plus. В этой статье мы рассмотрим процесс настройки и обработки вебхуков для вашей интеграции Sign.Plus.

Шаг 1: Создание вебхука

Чтобы начать получать обновления в реальном времени, необходимо сначала создать вебхук в Sign.Plus. Вот как:

1. Выберите целевой URL, в котором хотите получать уведомления о веб-хуке. Это должна быть конечная точка на вашем сервере, которая настроена на обработку входящих POST запросов.
2. Выберите событие, которое вы хотите отслеживать. Sign.Plus предлагает следующие события webhook:
   • конверт/законченный - После завершения конверта
   • Истек срок действия конверта - По истечении срока действия конверта
   • конверт отклонён - Когда конверт отклоняется
   • envelope_voided - When an envelope is voided
3. Используйте Sign.Plus API для создания вебхука. Вам нужно указать целевой URL и событие, которое вы хотите отслеживать.

Подробную информацию о том, как создать webhook с помощью Sign.Plus API, см. в разделе Create a webhook endpoint documentation.

Шаг 2: Обработка нотаций webhook

Как только вы настроили webhook, Sign.Plus будет отправлять POST запросы на указанный URL каждый раз, когда происходят отслеживаемые события. Вот что вам нужно знать о обработке этих уведомлений:

1. Метод запроса: Все уведомления webhook отправляются как HTTP POST запросов.
2. Payload Structure: Возобновляемая нагрузка вебхука является объектом JSON, содержащим два основных раздела:
   • hook: Содержит метаданные о самом вебхуке.
   • data: Содержит информацию о конверте, который вызвал событие.
3. Payload Примеры: Вот примеры полезных нагрузок для различных событий:
   // ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"конверт_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"конверт_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Обработка уведомления: Когда ваш сервер получает уведомление о вебхуках:
   • Проверьте загрузку приложения, чтобы убедиться, что это корректное уведомление webhook.
   • Извлечь соответствующую информацию из полезной нагрузки.
   • Выполнять любые необходимые действия на основе типа события (например, обновить базу данных, уведомить пользователей, триггер другие процессы).
   • Отправьте ответ200 OKдля подтверждения получения вебхука.

Передовая практика

1. Безопасность: Убедитесь, что ваш веб-хук защищён. Подумайте о внедрении аутентификации для URL-адреса вашего веб-хука.
2. Idempotency: Дизайн вашего обработчика веб-хука быть idempotent. Это означает, что он должен давать один и тот же результат, даже если один и тот же вебхук получает несколько раз.
3. Обработка ошибок: Реализовать ошибки при обработке веб-хука в логике.

Следуя этому руководству, вы сможете эффективно настроить и обрабатывать вебхуки, позволяет приложению получать в режиме реального времени новости о статусах конвертов в знаке. lus.