> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Управление вебхуками: создание, тестирование и аутентификация

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

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

<Note>
  Рабочие пространства тарифного плана Business Pro поддерживают до **30 000 событий вебхуков** в расчётный период. Проверьте ограничения вашего плана перед настройкой автоматизаций с высоким объёмом запросов.
</Note>

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

Вы можете подписать вебхук на любую комбинацию следующих событий:

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

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

<Steps>
  <Step title="Перейдите в управление вебхуками">
    В левой боковой панели перейдите в **Интеграции → Управление вебхуками**.
  </Step>

  <Step title="Аутентифицируйте токен">
    Нажмите кнопку **Управление**, чтобы аутентифицировать токен вебхука. Этот токен используется для подписи исходящих данных, чтобы вы могли убедиться, что они отправлены из AgencyHandy.
  </Step>

  <Step title="Создайте новый вебхук">
    Нажмите **Создать новый вебхук**, чтобы открыть форму настройки вебхука.
  </Step>

  <Step title="Введите URL конечной точки">
    В поле **URL конечной точки** введите URL внешней системы, которая должна получать данные вебхука. Это должна быть общедоступная конечная точка **POST**.
  </Step>

  <Step title="Выберите тип содержимого">
    Выберите **JSON** в качестве типа содержимого. AgencyHandy отправляет все данные вебхуков в формате `application/json`.
  </Step>

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

  <Step title="Активируйте вебхук">
    Переключите радиокнопку **Активен**. В активном состоянии AgencyHandy доставляет данные для всех выбранных событий на вашу конечную точку в режиме реального времени.
  </Step>

  <Step title="Сохраните настройки">
    Проверьте настройки, затем нажмите **Сохранить**. Вебхук появится в списке и немедленно начнёт доставлять события.
  </Step>
</Steps>

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

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

<Steps>
  <Step title="Откройте вебхук">
    В списке управления вебхуками нажмите на вебхук, который вы хотите протестировать.
  </Step>

  <Step title="Нажмите «Тестовое событие»">
    Нажмите кнопку **Тестовое событие** на странице сведений о вебхуке.
  </Step>

  <Step title="Выберите тестовое событие">
    Выберите образец события из списка событий, настроенных для этого вебхука (например, **Заказ: Создан**).
  </Step>

  <Step title="Отправьте тестовые данные">
    Нажмите **Отправить**. AgencyHandy опубликует образец данных на ваш URL конечной точки.
  </Step>

  <Step title="Проверьте результат">
    Проверьте вашу внешнюю систему, чтобы убедиться, что тестовые данные получены и обработаны корректно. Вернувшись в AgencyHandy, откройте вебхук для просмотра его **истории** — вы можете увидеть полный запрос, ответ вашей конечной точки и повторно доставить любое прошлое событие при необходимости.
  </Step>
</Steps>

<Tip>
  Используйте такие инструменты, как [Webhook.site](https://webhook.site) или [RequestBin](https://requestbin.com), в качестве временной конечной точки во время настройки, чтобы изучить точную структуру данных перед подключением реальной системы.
</Tip>

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

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

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

```
x-ah-sig: <signature>
```

AgencyHandy добавляет этот заголовок к каждому запросу вебхука. Извлеките значение из входящих запросов и передайте его в конечную точку проверки.

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

Отправьте следующий запрос для подтверждения подлинности данных:

```
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
```

<ParamField body="webhookId" type="string" required>
  Идентификатор вебхука, получившего событие. Найдите его на странице сведений о вебхуке в AgencyHandy.
</ParamField>

<ParamField body="signature" type="string" required>
  Значение заголовка `x-ah-sig` из входящего запроса вебхука.
</ParamField>

<ParamField body="secret" type="string" required>
  Секрет вебхука, отображаемый на странице сведений о вебхуке в AgencyHandy.
</ParamField>

<ParamField body="payload" type="object" required>
  Необработанное тело JSON, полученное из запроса вебхука AgencyHandy.
</ParamField>

<CodeGroup>
  ```javascript JavaScript theme={null}
  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" }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature \
    -H "Content-Type: application/json" \
    -d '{
      "webhookId": "your_webhook_id",
      "signature": "your_signature",
      "secret": "your_webhook_secret",
      "payload": {}
    }'
  ```
</CodeGroup>

**Ответы**

<ResponseField name="verification_status" type="string">
  `SUCCESS` при действительной подписи. `FAILED` при неудачной проверке (HTTP 403).
</ResponseField>

```json Success (200) theme={null}
{
  "verification_status": "SUCCESS"
}
```

```json Failure (403) theme={null}
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
```

<Warning>
  Храните секрет вебхука в тайне. Периодически обновляйте его и немедленно актуализируйте логику проверки после ротации. Никогда не раскрывайте его в клиентском коде или публичных репозиториях.
</Warning>

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

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