Перейти к основному содержанию
Вебхуки позволяют AgencyHandy мгновенно передавать данные во внешние системы при возникновении любого изменения — без необходимости опроса. Когда срабатывает настроенное событие (например, обновляется заказ или создаётся тикет), AgencyHandy отправляет HTTP POST-запрос с JSON-данными на указанный вами URL-адрес конечной точки. Это упрощает синхронизацию внешних инструментов — CRM-систем, систем выставления счетов или пользовательских панелей управления — с вашим рабочим пространством AgencyHandy в режиме реального времени.
Рабочие пространства тарифного плана Business Pro поддерживают до 30 000 событий вебхуков в расчётный период. Проверьте ограничения вашего плана перед настройкой автоматизаций с высоким объёмом запросов.

​
Поддерживаемые события

Вы можете подписать вебхук на любую комбинацию следующих событий:
КатегорияСобытия
УслугаСоздана, Обновлена, Удалена
ЗаказСоздан, Обновлён, Удалён
ЗадачаСоздана, Назначена, Выполнена, Обновлена
СчётСтатус изменён
Клиент / ПользовательДобавлен новый клиент, Клиент/пользователь удалён
ПредложениеОтправлено, Получено, Принято, Отклонено
ТикетСоздан, Назначен, Статус изменён
ПлатёжПолучен, Не выполнен
Пакет услугСоздан, Обновлён, Удалён

​
Создание вебхука

1

Перейдите в управление вебхуками

В левой боковой панели перейдите в Интеграции → Управление вебхуками.
2

Аутентифицируйте токен

Нажмите кнопку Управление, чтобы аутентифицировать токен вебхука. Этот токен используется для подписи исходящих данных, чтобы вы могли убедиться, что они отправлены из AgencyHandy.
3

Создайте новый вебхук

Нажмите Создать новый вебхук, чтобы открыть форму настройки вебхука.
4

Введите URL конечной точки

В поле URL конечной точки введите URL внешней системы, которая должна получать данные вебхука. Это должна быть общедоступная конечная точка POST.
5

Выберите тип содержимого

Выберите JSON в качестве типа содержимого. AgencyHandy отправляет все данные вебхуков в формате application/json.
6

Выберите события вебхука

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

Активируйте вебхук

Переключите радиокнопку Активен. В активном состоянии AgencyHandy доставляет данные для всех выбранных событий на вашу конечную точку в режиме реального времени.
8

Сохраните настройки

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

​
Тестирование вебхука

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

Откройте вебхук

В списке управления вебхуками нажмите на вебхук, который вы хотите протестировать.
2

Нажмите «Тестовое событие»

Нажмите кнопку Тестовое событие на странице сведений о вебхуке.
3

Выберите тестовое событие

Выберите образец события из списка событий, настроенных для этого вебхука (например, Заказ: Создан).
4

Отправьте тестовые данные

Нажмите Отправить. AgencyHandy опубликует образец данных на ваш URL конечной точки.
5

Проверьте результат

Проверьте вашу внешнюю систему, чтобы убедиться, что тестовые данные получены и обработаны корректно. Вернувшись в AgencyHandy, откройте вебхук для просмотра его истории — вы можете увидеть полный запрос, ответ вашей конечной точки и повторно доставить любое прошлое событие при необходимости.
Используйте такие инструменты, как Webhook.site или RequestBin, в качестве временной конечной точки во время настройки, чтобы изучить точную структуру данных перед подключением реальной системы.

​
Аутентификация данных вебхука

Каждый исходящий запрос вебхука из AgencyHandy содержит заголовок подписи, который ваша конечная точка может использовать для проверки подлинности данных и их целостности.

​
Заголовок подписи

x-ah-sig: <signature>
AgencyHandy добавляет этот заголовок к каждому запросу вебхука. Извлеките значение из входящих запросов и передайте его в конечную точку проверки.

​
Проверка подписи вебхука

Отправьте следующий запрос для подтверждения подлинности данных: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
обязательно
Идентификатор вебхука, получившего событие. Найдите его на странице сведений о вебхуке в AgencyHandy.
​
signature
string
обязательно
Значение заголовка x-ah-sig из входящего запроса вебхука.
​
secret
string
обязательно
Секрет вебхука, отображаемый на странице сведений о вебхуке в AgencyHandy.
​
payload
object
обязательно
Необработанное тело JSON, полученное из запроса вебхука AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Ответы
​
verification_status
string
SUCCESS при действительной подписи. FAILED при неудачной проверке (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Храните секрет вебхука в тайне. Периодически обновляйте его и немедленно актуализируйте логику проверки после ротации. Никогда не раскрывайте его в клиентском коде или публичных репозиториях.

​
Важные замечания

  • URL вашей конечной точки должен быть общедоступным HTTPS POST URL.
  • Если ваша конечная точка временно недоступна, проверьте панель истории вебхука в AgencyHandy — вы можете повторно доставить любое прошлое событие прямо оттуда.
  • Регулярно отслеживайте активность вебхуков для обнаружения сбоев доставки или несанкционированных попыток доступа.
  • Вебхуки, которые многократно не срабатывают, могут быть приостановлены AgencyHandy — проверяйте журналы доставки, чтобы выявлять проблемы заблаговременно.