## Что такое Server? {#what-is-server}

**Server** — это публичная региональная точка входа, через которую Adal принимает HTTP-вебхуки. Настройте его стабильный URL во внешнем сервисе, например GitHub, Stripe, Slack, Telegram, Discord, Dodo Payments, Make или Zapier.

Каждый принятый вебхук становится отдельным **Request**. Adal сохраняет полученные данные, чтобы вы могли проверить метод, путь, строку запроса, заголовки, тело, время получения, статус и историю доставки. Если у Server настроены один или несколько **Destinations**, Adal создаёт независимый **Delivery** для каждого Destination.

```text
Внешний сервис → Adal Server → Request
                                  ├── Delivery → Destination A
                                  └── Delivery → Destination B
```

Adal сохраняет исходные HTTP-метод, путь, строку запроса, заголовки и тело. Server не переписывает Request, не дополняет его бизнес-данными, не подтверждает личность отправителя вместо вашего приложения и не решает, как приложение должно обработать событие.

## Когда использовать Server {#when-to-use-servers}

Используйте Server, когда нужна стабильная и наблюдаемая точка приёма вебхуков. Типичные сценарии:

- разработка обработчика вебхуков без публикации локальной машины в интернете;
- проверка того, отправляет ли провайдер вебхук, и изучение фактического payload;
- замена временных URL туннеля стабильным URL приёма;
- диагностика ошибок Delivery или временной недоступности Destination;
- отправка одного Request в несколько Destinations;
- повторная попытка Delivery или replay сохранённого Request после изменения кода приложения;
- выбор региона, в котором Adal принимает и обрабатывает данные Requests;
- приём запросов из браузера, например отправка HTML-формы, если на Server включён CORS.

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

## Создание Server {#create-a-server}

Откройте [раздел Servers](https://dashboard.adal.cloud/servers), нажмите **Create server** и настройте следующие поля.

**Region**

Выберите, где Adal должен принимать и обрабатывать Requests этого Server. Регион становится частью публичного URL и не может быть изменён после создания.

**Name**

Укажите внутреннее название, которое объясняет назначение Server, например `GitHub development` или `Stripe production`. Название видно только в панели управления; оно не влияет на публичный URL или обработку Requests.

**Allowed methods**

Выберите только ожидаемые HTTP-методы. Adal поддерживает `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` и `PUT`. Request с отключённым методом отклоняется при приёме. Большинство провайдеров вебхуков используют `POST`, но для проверки или нестандартного сценария может применяться другой метод.

**IP access restrictions**

При необходимости ограничьте, с каких IP-адресов клиенты могут отправлять Requests на этот Server. Фильтрация может быть выключена, принимать только перечисленные адреса и CIDR-диапазоны либо принимать все адреса, кроме перечисленных. См. [Ограничения по IP](#ip-access-restrictions).

**Content-Type restrictions**

При необходимости ограничьте допустимые значения заголовка `Content-Type`. Режимы фильтра совпадают с IP-ограничениями: выключен, принимать только перечисленные типы или принимать все, кроме перечисленных. Поддерживаются точные типы, например `application/json`, и маски подтипа, например `image/*`. См. [Ограничения по Content-Type](#content-type-restrictions).

**Deliver pending requests on connect**

Этот параметр определяет поведение при повторном подключении Adal CLI:

- если он включён, сохранённые ожидающие Requests могут быть доставлены после подключения CLI;
- если он выключен, CLI получает только новые Requests, поступившие после подключения, а старые ожидающие Requests не доставляются автоматически.

**Response status code**

Выберите HTTP-статус, который Adal возвращает отправителю после приёма. См. [Ответ отправителю](#response-to-the-sender).

**Allow CORS**

Включите CORS-заголовки ответа, если на Server нужно принимать запросы из браузера, например отправку HTML-формы или другие вызовы с фронтенда. См. [Ответ отправителю](#response-to-the-sender).

**Response Content-Type и content**

Выберите `Content-Type` ответа, который Adal возвращает отправителю, и при необходимости укажите статическое тело ответа. См. [Ответ отправителю](#response-to-the-sender).

**Notes**

Используйте заметки для внутреннего контекста. Они не влияют на приём, Delivery или внешние интеграции. Не помещайте в это поле учётные данные или payload вебхуков.

После сохранения скопируйте публичный URL приёма Server. Если панель управления показывает CLI token, сразу сохраните его и обращайтесь с ним как с секретом.

## Ограничения по IP {#ip-access-restrictions}

Ограничения по IP фильтруют Requests по IP-адресу отправителя до того, как Request попадает в обычный процесс Delivery.

Выберите один режим:

- **Do not restrict access** — IP-адреса не участвуют в фильтрации приёма.
- **Allow access only from listed addresses** — Adal принимает Requests только с перечисленных IPv4-адресов, IPv6-адресов и CIDR-диапазонов. Все остальные источники отклоняются.
- **Block access from listed addresses** — Adal принимает Requests от всех источников, кроме перечисленных IPv4-адресов, IPv6-адресов и CIDR-диапазонов.

Указывайте по одному адресу или CIDR-диапазону на строку. Примеры:

```text
203.0.113.10
198.51.100.0/24
2001:db8::1
2001:db8:abcd::/48
```

Если выбран режим, отличный от **Do not restrict access**, список должен содержать хотя бы одну корректную запись. Requests, отклонённые IP-фильтром, не попадают в обычный процесс Delivery и сохраняют только минимальную диагностическую запись, описанную в разделе [Входящие Requests](#incoming-requests).

Фильтрация по IP — это ограничение приёма на уровне Server. Она не заменяет проверку подписей провайдера и аутентификацию отправителя в обработчике Destination.

## Ограничения по Content-Type {#content-type-restrictions}

Ограничения по Content-Type фильтруют Requests по заголовку `Content-Type` по той же схеме режимов, что и ограничения по IP.

Выберите один режим:

- **Disabled** — `Content-Type` не участвует в фильтрации приёма.
- **Accept only listed Content-Types** — Adal принимает Requests только когда `Content-Type` запроса совпадает с записью из списка. Остальные Requests отклоняются.
- **Reject listed Content-Types** — Adal принимает Requests, если `Content-Type` запроса не совпадает ни с одной записью из списка.

Указывайте по одному Content-Type на строку. Можно задавать точные типы или использовать `*` как маску подтипа:

```text
application/json
application/x-www-form-urlencoded
image/*
```

В этом примере `image/*` соответствует типам вроде `image/png` и `image/jpeg`.

Если выбран режим, отличный от **Disabled**, список должен содержать хотя бы одну запись. Requests, отклонённые фильтром Content-Type, не попадают в обычный процесс Delivery и сохраняют только минимальную диагностическую запись.

Фильтрация по Content-Type помогает отсекать неожиданные payload на этапе приёма. Обработчик Destination по-прежнему должен проверять заголовки и тело перед выполнением действий.

## Ответ отправителю {#response-to-the-sender}

После успешного приёма входящего Request Adal возвращает отправителю настроенный HTTP-ответ. Этот ответ отделён от Delivery в Destination: успешный ответ приёма не означает, что каждый Destination завершил свою работу.

### Response status code

Выберите код ответа из списка, доступного в панели управления:

- `200 OK`
- `201 Created`
- `202 Accepted`
- `204 No Content`
- `400 Bad Request`
- `401 Unauthorized`
- `403 Forbidden`
- `404 Not Found`
- `409 Conflict`
- `422 Unprocessable Content`
- `429 Too Many Requests`
- `500 Internal Server Error`
- `502 Bad Gateway`
- `503 Service Unavailable`

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

### Allow CORS

Если **Allow CORS** включён, Adal возвращает CORS-заголовки, разрешающие origin запроса, в том числе для preflight-запросов `OPTIONS`. Так на Server можно отправлять трафик из браузера, например HTML-формы или другие HTTP-вызовы с фронтенда.

Если CORS выключен, кросс-доменные запросы из браузера могут завершаться ошибкой, даже когда тот же запрос от небраузерного клиента Server принял бы.

Поддержка CORS не аутентифицирует отправителя и не заменяет проверку на стороне Destination.

### Response Content-Type

Выберите `Content-Type` ответа, возвращаемого отправителю. В панели управления есть распространённые варианты:

- `application/json`
- `text/html`
- `text/plain`
- `application/xml`
- `text/xml`
- `application/octet-stream`

Также можно выбрать произвольный Content-Type и указать значение, например `application/problem+json`.

### Response content

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

Оставляйте тело пустым, если выбранный статус или Content-Type не требуют содержимого либо отправитель игнорирует тело ответа.

## URL Server {#server-url}

У каждого Server есть стабильный публичный URL, который действует, пока существует сам Server. Используйте точный URL из панели управления; в документации приведены только заполнители:

```text
https://your-server-id.region.adal.cloud
```

Внешние сервисы могут отправлять запросы на корневой URL или вложенный путь:

```text
https://your-server-id.region.adal.cloud/github/push
```

Поддерживаются строки запроса:

```text
https://your-server-id.region.adal.cloud/github/push?source=test
```

Путь и строка запроса относятся к тому же Server и сохраняются вместе с Request. Они не создают дополнительные Servers.

Не удаляйте Server, пока его URL настроен во внешнем сервисе. После удаления URL становится неактивным, а удалённые поддомены Server не используются повторно.

## Регионы {#regions}

Каждый Server относится к одному региону обработки. Выбранный регион:

- становится частью URL Server;
- принимает и обрабатывает входящие Requests;
- определяет место хранения региональных данных Requests;
- применяется к связанным с этими Requests Deliveries.

Выбирайте регион с учётом инфраструктуры, пользователей, местоположения отправителей и требований к размещению данных. Регион существующего Server изменить нельзя. Для перехода создайте новый Server в другом регионе и обновите URL вебхука во всех отправляющих сервисах.

Доступность регионов и их список могут меняться. Используйте актуальный список в панели управления, а не идентификатор региона из примера.

## Входящие Requests {#incoming-requests}

Каждый принятый HTTP-запрос становится отдельным Request. В зависимости от настроек хранения и retention Server можно проверить:

- HTTP-метод и полный URI;
- путь и строку запроса;
- заголовки и тело;
- IP-адрес отправителя;
- время получения и размер запроса;
- статус, Deliveries и историю попыток.

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

Request может быть принят и доступен для просмотра, даже если локальное приложение выключено, CLI отключён или Destination временно недоступен — при условии, что Request соответствует правилам приёма и выбранная конфигурация сохраняет его.

Отклонённые Requests не попадают в обычный процесс Delivery. Для диагностики Adal сохраняет только метод, время получения и причину отклонения. URI, путь, строка запроса, заголовки, тело, IP-адрес отправителя и данные Delivery не сохраняются. Отклонение возможно, например, из-за отключённого HTTP-метода, ограничений по IP, ограничений по Content-Type, превышения размера, нехватки кредитов или недоступности региона.

## Пути и параметры запроса {#paths-and-query-parameters}

Один Server может принимать связанные источники вебхуков на разных путях:

```text
https://your-server-id.region.adal.cloud/github/push
https://your-server-id.region.adal.cloud/github/issues
https://your-server-id.region.adal.cloud/github/releases
```

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

Разные пути не являются изолированными Servers. У них общие регион, разрешённые методы, ограничения по IP и Content-Type, настройки ответа, лимиты, retention и Destinations. Создавайте отдельные Servers, когда нужны разные публичные URL или разные настройки уровня Server.

## Ограничения Requests {#request-limits}

Приём зависит от текущего плана и конфигурации Server. Adal рассчитывает общий размер запроса так:

```text
размер запроса = размер URI + размер заголовков + размер тела
```

Поэтому длинный URI или большие заголовки могут превысить ограничение даже при небольшом теле. Request также может быть отклонён, если его HTTP-метод отключён, IP отправителя не проходит ограничения по IP, `Content-Type` запроса не проходит ограничения по Content-Type, Server больше не существует, аккаунт не может принять ещё один Request или принимающий регион недоступен.

Для отклонённых Requests сохраняется только минимальная диагностическая запись, описанная выше. Проверяйте [актуальные планы и ограничения](/pricing), а не переносите значения из документации в код приложения.

## Кредиты {#credits}

Согласно текущей модели оплаты кредиты учитывают принятые Requests и ручные операции:

- один принятый входящий Request использует один кредит;
- обычное хранение, автоматические попытки Delivery и автоматические повторы этого Request входят в тот же кредит;
- отклонённый Request не использует кредит;
- replay Request использует один дополнительный кредит;
- ручная повторная попытка Delivery использует один дополнительный кредит.

Если аккаунт не может потратить требуемый кредит, Adal не может принять входящий вебхук как обычный Request. Правила оплаты и ограничения планов могут меняться — проверяйте [страницу тарифов](/pricing) и панель управления.

## Requests, полученные Server {#requests-in-a-server}

Server может получить много Requests. У каждого принятого HTTP-запроса есть собственные идентификатор, время получения, статус, срок хранения при его наличии и связанные Deliveries.

```text
Server
├── Request #1
├── Request #2
└── Request #3
```

Наличие Request подтверждает, что Adal принял вебхук. Это не означает, что его получил каждый Destination или что во внешней системе завершилась бизнес-операция. Откройте Request и проверяйте каждый Delivery отдельно.

Отклонённые Requests могут отображаться рядом с принятыми, но содержат только минимальную диагностическую информацию и не имеют Deliveries.

## Destinations {#destinations}

Destination указывает Adal, куда доставлять принятые Requests. Он относится к одному Server и может использовать прямую HTTP-доставку в доступный сервис или доставку через Adal CLI в локальный либо закрытый сервис.

У Server может быть несколько Destinations в пределах ограничений текущего плана. Adal создаёт и отслеживает отдельный Delivery для каждого Destination, поэтому один маршрут может завершиться успешно, а другой — ошибкой.

Server без Destinations всё равно может принимать Requests для просмотра, если выбранная конфигурация сохраняет их, но автоматически никуда их не пересылает.

Параметры соединения, правила повторных попыток и настройки конкретной доставки задаются в Destination, а не в Server.

## Порядок Delivery {#delivery-behavior}

После приёма Request Adal создаёт Delivery для каждого настроенного Destination и независимо фиксирует попытки.

```text
Server → Request
         ├── Delivery A → Attempt → 2xx
         └── Delivery B → Attempt → Failure → Retry
```

Если Destination недоступен или возвращает ответ, требующий новой попытки, Adal может выполнить повтор согласно конфигурации Destination. Автоматические повторы относятся к обычной обработке. Ручной повтор является отдельной операцией.

Успешный Delivery означает, что Adal получил ожидаемый HTTP-ответ от Destination. Он не подтверждает, что Destination завершил обновление базы, платёж, отправку уведомления или другую бизнес-операцию.

Повторные попытки, несколько Destinations и replay могут создавать дубли или повторные побочные эффекты. Обработчики Destination должны валидировать данные, проверять подписи провайдера, быть идемпотентными, устранять дубли по стабильному идентификатору события при его наличии и учитывать частичные ошибки.

## Replay {#replay}

Replay создаёт новый Request на основе ранее полученного и снова отправляет его через текущий процесс Server. Исходный Request не изменяется.

```text
Исходный Request → Replay → Новый Request → Новые Deliveries
```

Replay полезен после исправления обработчика или при воспроизведении ошибки Delivery без ожидания повторного события от отправителя. Он доступен только пока Adal хранит исходные данные, необходимые для воссоздания Request.

Новый Request ссылается на исходный, поэтому их можно различить в панели управления. Replay отличается от ручного повтора: replay создаёт новый Request и новые Deliveries, а ручной повтор заново выполняет конкретный существующий Delivery.

Replay может доставить одно событие провайдера несколько раз и согласно текущей модели оплаты использует дополнительный кредит. До запуска убедитесь, что все затронутые обработчики безопасно выполнять повторно.

## Безопасность Server {#security-notes}

URL Server является публичным: любой, кто его знает, может отправить подходящий HTTP-запрос. Считайте его чувствительным адресом интеграции, но не воспринимайте знание URL как подтверждение личности отправителя.

Ограничения по IP и Content-Type снижают нежелательный приём, но не являются аутентификацией. Обработчик Destination по-прежнему отвечает за:

- проверку подписи вебхука или другого доказательства подлинности от отправителя;
- валидацию метода, типа содержимого, заголовков и payload до выполнения действий;
- сравнение за постоянное время и соблюдение процедуры подписи провайдера, где это применимо;
- идемпотентность и устранение повторных событий;
- защиту учётных данных, которые могут находиться в URL, строках запроса, заголовках или теле.

Разрешайте только ожидаемые HTTP-методы, настраивайте фильтры по IP и Content-Type, когда это соответствует вашей модели угроз, и выбирайте подходящую конфигурацию retention. Включение CORS расширяет круг тех, кто может вызывать Server из браузера; сочетайте его с другими ограничениями приёма осознанно. Не копируйте содержимое клиентских вебхуков, URL Server, токены или учётные данные Destination в обычные логи, аналитику, отчёты об ошибках или обращения в поддержку.

Adal сохраняет данные запроса, необходимые для проверки подписи, но обработчик должен сформировать и проверить подписываемые данные точно по документации провайдера.

## Удаление Server {#delete-a-server}

Перед удалением Server удалите или замените его URL во всех внешних сервисах. Удаление:

- останавливает приём новых запросов этим Server;
- делает публичный URL неактивным;
- удаляет Destinations этого Server;
- не освобождает и не использует повторно его поддомен;
- не удаляет мгновенно ранее принятые Requests — они могут храниться до запланированного окончания retention.

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

До удаления проверьте сохранённые Requests и потребность в replay или аудите. Adal не является постоянным архивом, поэтому переносите бизнес-данные в системы, рассчитанные на требуемые сроки хранения.

## Устранение неполадок {#troubleshooting}

**Вебхук не виден в Adal**

Проверьте полный URL Server и регион, существование Server, разрешённые методы, ограничения по IP, ограничения по Content-Type, общий размер запроса, доступные кредиты и доступность региона. Найдите отклонённую запись и причину отклонения.

**Request отклонён**

Проверьте, разрешён ли HTTP-метод, проходит ли IP отправителя ограничения по IP, проходит ли `Content-Type` запроса ограничения по Content-Type, и не превышает ли сумма размеров URI, заголовков и тела текущее ограничение. Отклонённый Request содержит только минимальные диагностические данные.

**Запрос из браузера падает с ошибкой CORS**

Убедитесь, что на Server включён **Allow CORS**, что используется разрешённый HTTP-метод, и что браузер обращается к точному URL Server из панели управления.

**Провайдер сообщает об успехе, но тело ответа неожиданное**

Проверьте код ответа Server, Content-Type ответа и статическое тело ответа. Ответ приёма, возвращаемый отправителю, настраивается на Server и не зависит от результатов Delivery в Destination.

**Request существует, но не доставлен**

Откройте список Deliveries. Проверьте наличие и состояние Destination, подключение CLI при необходимости, доступность целевого URL, а также ответ или ошибку каждой попытки. Один Destination может завершиться ошибкой, когда другой работает успешно.

**Ожидающие Requests не поступают после подключения CLI**

Проверьте **Deliver pending requests on connect** у Server и убедитесь, что Requests всё ещё хранятся и имеют ожидающий статус. Если параметр выключен, подключение CLI не доставляет старые ожидающие Requests автоматически.

**Провайдер сообщает об ошибке**

Если Request отсутствует, проверяйте приём: URL, регион, разрешённый метод, фильтры по IP и Content-Type, размер, кредиты и доступность. Если Request существует, проверяйте Destination, историю попыток и целевое приложение. Также сравните настроенный ответ приёма с тем, что ожидает провайдер.

**Нужно остановить пересылку и сохранить URL**

Не удаляйте Server. Удалите или отключите его Destinations, затем убедитесь, что итоговое поведение приёма и retention соответствует требованиям.

## Связанные страницы {#related-pages}

- [Быстрый старт](/docs/quickstart)
- [Основные понятия](/docs/concepts)
- [Requests](/docs/requests)
- [Destinations](/docs/destinations)
- [Повторные попытки и replay](/docs/retries)
- [Хранение данных и retention](/docs/storage)
- [Adal CLI](/docs/adal-cli)