Помощь
Чат для вопросов по API
Мгновенно ответим на ваши вопросы
api@ati.su
Электронная почта техподдержки
Тикетная система
Оставить заявку на отдел
«Консультанты по интеграции (API)»
api.ati.su - заказы, торги, площадки
Наш телеграм-канал
Код в АТИ:
Выход

Вебхуки

Вебхуки предоставляют возможность получать обновления по интересующим темам, как только они произошли в системе ATI.SU.

Требования к вебхукам

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

  • не является открытым и угадываемым, то есть третьи лица не должны иметь возможности узнать о его существовании;
  • если используется DNS-имя, оно должно разрешаться в публичный1 IPv4 адрес;
  • если используется IP-адрес, он должен быть публичным1 IPv4 адресом;
  • доступен по протоколу HTTPS;
  • уникален на каждую подписку.

Рекомендации по реализации

1. Время ответа

На ответ вебхуку дается 20 секунд, поэтому рекомендуется реализовывать его таким образом, чтобы ответ означал факт получения сообщения, а не его обработки.

2. Уникальность

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

3. TLS

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

Использование API

Для существования вебхука необходимы два метода по одному URL. Первый (GET) отвечает за управление состоянием, а второй (POST) — за передачу сообщений.

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

Создание вебхука происходит в два этапа: отправка запроса на создание и верификация.

Отправка запроса на создание

При отправке запроса на создание необходимо выбрать тему подписки.

Параметр callback должен содержать URL вебхука. В URL допустимы параметры запроса, которые будут переданы при вызове вебхука. Параметры запроса можно использовать, например, для привязки вебхука к пользователю: https://example.org/webhook?userId=00000000.

 
Создать вебхук
post
/webhooks/v1/create
Развернуть все Свернуть все
{...}

Запрос создания вебхука

topic: string

Тема

callback: string

URL

}
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
202
Развернуть все Свернуть все
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...
 
Создать вебхук
post
/gw/oauth2/webhooks/v1/create
Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна
Развернуть все Свернуть все
{...}

Запрос создания вебхука

topic: string

Тема

callback: string

URL

}
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
202
Развернуть все Свернуть все
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...

В ответе содержится заголовок Location с URL GET-метода проверки состояния созданного вебхука.

Верификация

После отправки запроса на создание, вебхук проходит верификацию. Вызывается GET метод по URL вебхука с параметрами challenge и topic, а также параметрами указанными при создании.

Пример верификационного запроса
GET /webhook?status=verification&verification_status=progress&topic=orders&challenge=608b672ed0a5aaecc2d42488 HTTP/1.1
Host: example.org
Accept: application/json

Вебхук должен ответить в течение 20 секунд на верификационный запрос JSON-строкой с содержимым параметра challenge.

Пример ответа на верификационный запрос
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26

"608b672ed0a5aaecc2d42488"

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

Если верификация провалилась, узнать причину можно с помощью метода проверки состояния вебхука. Вебхук будет находиться в состоянии verification.

Проверка состояния вебхука

Проверка состояния одного Веб-хука

 
Получить состояние вебхука
get
/webhooks/v1/status/{id}
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
200
Развернуть все Свернуть все
Пример Модель
{...}
"verification":{},
"hook":{...}
"id":"string",
"callback":"string",
"topic":"string",
"application_id":"string",
"contact_id":0
}
}
{...}

Состояние вебхука

status: enum
[created, verification, active, removed, deactivated]

Идентификатор состояния вебхука

  • created — Создан

  • verification — Проверяется

  • active — Активен

  • removed — Удален

  • deactivated — Деактивирован

    Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

}
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...
 
Получить состояние вебхука
get
/gw/oauth2/webhooks/v1/status/{id}
Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
200
Развернуть все Свернуть все
Пример Модель
{...}
"verification":{},
"hook":{...}
"id":"string",
"callback":"string",
"topic":"string",
"application_id":"string",
"contact_id":0
}
}
{...}

Состояние вебхука

status: enum
[created, verification, active, removed, deactivated]

Идентификатор состояния вебхука

  • created — Создан

  • verification — Проверяется

  • active — Активен

  • removed — Удален

  • deactivated — Деактивирован

    Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

}
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...

Проверка состояния нескольких Веб-хуков

 
Получить состояние нескольких вебхуков
get
/webhooks/v1/status
statuses
array
Добавить еще поле

Идентификатор состояния вебхука

  • created — Создан
  • verification — Проверяется
  • active — Активен
  • removed — Удален
  • deactivated — Деактивирован

Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
200
Развернуть все Свернуть все
Пример Модель
[...]
{...}
"verification":{},
"hook":{...}
"id":"string",
"callback":"string",
"topic":"string",
"application_id":"string",
"contact_id":0
}
}
]
[{...}]

Состояние вебхука

status: enum
[created, verification, active, removed, deactivated]

Идентификатор состояния вебхука

  • created — Создан

  • verification — Проверяется

  • active — Активен

  • removed — Удален

  • deactivated — Деактивирован

    Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

}]
Загрузка...
Развернуть все Свернуть все
Загрузка...
 
Получить состояние нескольких вебхуков
get
/gw/oauth2/webhooks/v1/status
Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна
statuses
array
Добавить еще поле

Идентификатор состояния вебхука

  • created — Создан
  • verification — Проверяется
  • active — Активен
  • removed — Удален
  • deactivated — Деактивирован

Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
200
Развернуть все Свернуть все
Пример Модель
[...]
{...}
"verification":{},
"hook":{...}
"id":"string",
"callback":"string",
"topic":"string",
"application_id":"string",
"contact_id":0
}
}
]
[{...}]

Состояние вебхука

status: enum
[created, verification, active, removed, deactivated]

Идентификатор состояния вебхука

  • created — Создан

  • verification — Проверяется

  • active — Активен

  • removed — Удален

  • deactivated — Деактивирован

    Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

}]
Загрузка...
Развернуть все Свернуть все
Загрузка...

Оповещения о смене состояния вебхука

GET-метод по URL вебхука используется также для оповещений о смене его (вебхука) состояния. Во все вызовы передается парметр topic, обозначающий тему подписки.

Событие Параметры Описание
Провал верификации status: verification
verification_status: failed
Проблемы с верификацией.
Провал отправки distribution_status: failed
since: YYYY-MM-DDThh:mm:ss
Проблемы с отправкой сообщения. В параметре since указана дата первой проваленной отправки.
Провал повторной отправки distribution_status: failed_retry
failed_count: число
Проблемы с повторной отправкой сообщений. В параметре failed_count указано количество повторно отправляемых сообщений.
Остальные изменения состояния вебхука status: одно из значений поля status

Оповещение о смене статуса не ожидает ответа.

Получение сообщений

При возникновении события, вызывается POST метод вебхука с параметром topic. В теле запроса передается обновленная сущность (параметр entity) и другие параметры события.

Соответствие порядка возникновения событий и отправки сообщений не гарантируется. Поэтому, при получении сообщения, необходимо сравнивать параметр action_date текущего и предыдущего сообщений.

Тело запроса
Развернуть все Свернуть все
Пример Модель
{...}
"entity_id":"string",
"action_date":"1970-01-01T00:00:00.000Z",
"entity":null
}
{...}

Отправляемое сообщение

entity_id: string

Id отправляемой сущности

action_date: date-time

Дата события

entity: {missing-type-info}

Отправляемая сущность

}
Пример отправки сообщения
POST /webhook?topic=orders HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 179

[{"entity_id": "4ea8c372-9510-4880-a80d-fb9ac19129cf", "action_date": "2021-04-30T05:12:41.687Z", "entity": {"id": "4ea8c372-9510-4880-a80d-fb9ac19129cf"}}]

Ожидается ответ с кодом 2xx (Successful)2 на протяжении 20 секунд. В ином случае отправка помечается проваленной, и отправляется оповещение об изменении состояния вебхука.

Для временной приостановки получения сообщений, можно использовать ответ 429 (Too Many Requests)3 с заголовком Retry-After4. Приостановка возможна не более чем на 1 день.

Если был получен ответ 410 (Gone)5, вебхук удаляется без возможности восстановления.

Повторные отправки

Как только вебхук успешно примет сообщение, будет предпринята попытка повторно отправить сообщения, отправка которых провалилась ранее. Отличить повторную отправку от первоначальной можно по значению true в заголовке ATI-Is-Retry запроса. В случае провала повторной отправки, она будет отложена до успешного получения вебхуком нового сообщения.

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

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

 
Получить проваленные отправки
get
/webhooks/v1/distributions/failed/{id}
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
200
Развернуть все Свернуть все
Пример Модель
[...]
{...}
"entity_id":"string",
"action_date":"1970-01-01T00:00:00.000Z",
"status":"failed",
"entity":null
}
]
[{...}]

Проваленная отправка сообщения

entity_id: string

Id отправляемой сущности

action_date: date-time

Дата события

status: enum
[failed]

Идентификатор состояния отправки

  • failed — Провалена
entity: {missing-type-info}

Отправляемая сущность

}]
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...
 
Получить проваленные отправки
get
/gw/oauth2/webhooks/v1/distributions/failed/{id}
Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
200
Развернуть все Свернуть все
Пример Модель
[...]
{...}
"entity_id":"string",
"action_date":"1970-01-01T00:00:00.000Z",
"status":"failed",
"entity":null
}
]
[{...}]

Проваленная отправка сообщения

entity_id: string

Id отправляемой сущности

action_date: date-time

Дата события

status: enum
[failed]

Идентификатор состояния отправки

  • failed — Провалена
entity: {missing-type-info}

Отправляемая сущность

}]
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...

Удаление вебхука

При удалении вебхука, прекращается отправка сообщений в него, а также удаляются его проваленные отправки.

 
Удалить вебхук
delete
/webhooks/v1/delete/{id}
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
202
Развернуть все Свернуть все
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...
 
Удалить вебхук
delete
/gw/oauth2/webhooks/v1/delete/{id}
Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна
CURL 1C
CURL
Копировать

                
1C
Копировать

                
Пример ответа Ответ
202
Развернуть все Свернуть все
4XX Ошибка запроса. Подробнее про ошибки API
Развернуть все Свернуть все
Пример Модель
{...}
"error_code":"string",
"reason":"string",
"details":"?",
"error_list":[...]
{}
]
}
{...}

Описание ошибки

error_code: string

Код ошибки

reason: string

Причина ошибки

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки

}
Загрузка...
Развернуть все Свернуть все
Загрузка...

  1. RFC 1918 | Private Address Space ↩︎

  2. RFC 7231 | Successful 2xx ↩︎

  3. RFC 6585 | 429 Too Many Requests ↩︎

  4. RFC 7231 | Retry-After ↩︎

  5. RFC 7231 | 410 Gone ↩︎