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

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

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

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

1. Определите целевой URL-адрес, на который вы хотите получать уведомления вебхука. Это должна быть конечная точка на вашем сервере, настроенная для обработки входящих POST-запросов.
2. Выберите события, которые нужно отслеживать. Sign.Plus предлагает следующие события вебхука:
   • envelope_completed

      — когда конверт завершён

   • envelope_expired

      — когда срок действия конверта истёк

   • envelope_declined

      — когда конверт отклонён

   • envelope_voided

      — когда конверт аннулирован

3. Используйте API Sign.Plus для создания вебхука. Вам нужно указать целевой URL-адрес и события, которые нужно отслеживать.

Подробную информацию о создании вебхука с помощью API Sign.Plus см. в документации по конечной точке создания вебхука.

Шаг 2: обработка уведомлений вебхука

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

1. Метод запроса: все уведомления вебхуков отправляются в виде HTTP 

   POST

    запросов.

2. Структура полезной нагрузки: полезная нагрузка вебхука представляет собой объект JSON, содержащий два основных раздела:
   • hook

     : содержит метаданные о самом вебхуке.

   • data

     : содержит информацию о конверте, вызвавшем событие.

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

   // 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",
"envelope_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",
"envelope_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. Обработка уведомления: когда ваш сервер получает уведомление вебхука:
   • Проверьте полезную нагрузку, чтобы убедиться, что это действительное уведомление вебхука.
   • Извлеките необходимую информацию из полезной нагрузки.
   • Выполните необходимые действия в зависимости от типа события (например, обновите базу данных, уведомите пользователей, запустите другие процессы).

   • Отправьте ответ 

     200 OK

     , чтобы подтвердить получение вебхука.

Вебхуки Sign.Plus отправляются только с указанных ниже авторизованных IP-адресов:
34.65.253.117
34.65.146.131

Рекомендации по использованию

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

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