Вебхуки

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

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

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

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

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

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

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

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

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

Чтобы подписаться на события через вебхуки, необходимо выбрать тему и указать её в параметре topic. Для тем подписки, которые позволяют подписаться на события по чужим сущностям, необходимо задать тип подписки complex в параметре subscription_type, а также заполнить параметры фильтра в соответствии с темой и указать их в параметре subscription запроса на создание вебхука.

Параметр subscription

Развернуть все

Свернуть все

Пример

Модель

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

Каналы подписки

cargoes.on_boards — Грузы на площадках
auctions.on_boards — Торги на площадках

boards: [string]

Идентификаторы площадок для подписки

boards: [string]

Идентификаторы площадок для подписки

}

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

Создать вебхук

post

/webhooks/v1/create

Развернуть все Свернуть все

body

object

{...}

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

subscription_type: enum (nullable)

[normal, complex]

Тип подписки вебхука

normal — Обычная
complex — С возможностью настройки фильтров

topic: string

Тема

callback: string

URL

subscription: {missing-type-info}

Параметры подписки с возможностью настройки фильтров

topic: string

Тема

callback: string

URL

}

CURL

Копировать

Пример ответа

Ответ

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 временно недоступна

Развернуть все Свернуть все

body

object

{...}

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

subscription_type: enum (nullable)

[normal, complex]

Тип подписки вебхука

normal — Обычная
complex — С возможностью настройки фильтров

topic: string

Тема

callback: string

URL

subscription: {missing-type-info}

Параметры подписки с возможностью настройки фильтров

topic: string

Тема

callback: string

URL

}

CURL

Копировать

Пример ответа

Ответ

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:443
Date: Thu, 01 Jan 1970 00:00:00 GMT
Digest: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Accept: application/json
Authorization: HMAC-SHA-256 Credential=6447f577905114d5b9b2c618&SignedHeaders=Date;Digest;Host&Signature=IFfS27QZuXLTNV9idpwnUNDSiayHYAJO0IcoJy2pHy8=

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

Верификационный запрос, так же как и все остальные, имеет заголовок Authorization, поэтому возможна его аутентификация. При его поступлении следует получить сгенерированный ключ с помощью метода проверки состояния вебхука (поле hook.key).

Пример ответа на верификационный запрос

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26

"608b672ed0a5aaecc2d42488"

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

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

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

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

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

get

/webhooks/v1/status/{id}

string

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

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

{...}

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

status: enum

[created, verification, active, removed, deactivated]

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

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

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

hook:{...}

Деактивированный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:{...}

Активный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:{...}

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

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

verification:{...}

Проверка вебхука

status: enum

[progress, failed]

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

progress — Выполнение
failed — Провалена

fail_reason: enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

unknown_error — Неизвестная ошибка

Ошибка на стороне ATI.SU
tls_error — Ошибка установки защищенного соединения

Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS
socket_error — Ошибка создания TCP соединения

Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы
request_error — Ошибка запроса

Получен HTTP-код, отличный от 200, или превышено время ожидания ответа
challenge_mismatch — Challenge не совпадает
wrong_response_format — Неправильный формат ответа

Формат ответа отличается от JSON-строки

}

hook:{...}

Проверяемый вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

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 временно недоступна

string

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

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

{...}

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

status: enum

[created, verification, active, removed, deactivated]

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

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

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

hook:{...}

Деактивированный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:{...}

Активный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:{...}

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

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

verification:{...}

Проверка вебхука

status: enum

[progress, failed]

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

progress — Выполнение
failed — Провалена

fail_reason: enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

unknown_error — Неизвестная ошибка

Ошибка на стороне ATI.SU
tls_error — Ошибка установки защищенного соединения

Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS
socket_error — Ошибка создания TCP соединения

Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы
request_error — Ошибка запроса

Получен HTTP-код, отличный от 200, или превышено время ожидания ответа
challenge_mismatch — Challenge не совпадает
wrong_response_format — Неправильный формат ответа

Формат ответа отличается от JSON-строки

}

hook:{...}

Проверяемый вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

4XX Ошибка запроса. Подробнее про ошибки API

Развернуть все Свернуть все

Пример

Модель

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Загрузка...

Развернуть все Свернуть все

Загрузка...

Для тем подписки с фильтром также доступно получение параметров фильтра.

Получить параметры фильтра

get

/webhooks/v1/subscriptions/{id}

string

Id вебхука

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

Каналы подписки

cargoes.on_boards — Грузы на площадках
auctions.on_boards — Торги на площадках

boards: [string]

Идентификаторы площадок для подписки

boards: [string]

Идентификаторы площадок для подписки

}

Загрузка...

Развернуть все Свернуть все

Загрузка...

Получить параметры фильтра

get

/gw/oauth2/webhooks/v1/subscriptions/{id}

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

string

Id вебхука

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

Каналы подписки

cargoes.on_boards — Грузы на площадках
auctions.on_boards — Торги на площадках

boards: [string]

Идентификаторы площадок для подписки

boards: [string]

Идентификаторы площадок для подписки

}

Загрузка...

Развернуть все Свернуть все

Загрузка...

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

Получить состояние нескольких вебхуков

get

/webhooks/v1/status

statuses

array

Добавить еще поле

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

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

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

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

[...]

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

]

[{...}]

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

status: enum

[created, verification, active, removed, deactivated]

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

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

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

hook:{...}

Деактивированный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:{...}

Активный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:{...}

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

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

verification:{...}

Проверка вебхука

status: enum

[progress, failed]

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

progress — Выполнение
failed — Провалена

fail_reason: enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

unknown_error — Неизвестная ошибка

Ошибка на стороне ATI.SU
tls_error — Ошибка установки защищенного соединения

Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS
socket_error — Ошибка создания TCP соединения

Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы
request_error — Ошибка запроса

Получен HTTP-код, отличный от 200, или превышено время ожидания ответа
challenge_mismatch — Challenge не совпадает
wrong_response_format — Неправильный формат ответа

Формат ответа отличается от JSON-строки

}

hook:{...}

Проверяемый вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

}]

Загрузка...

Развернуть все Свернуть все

Загрузка...

Получить состояние нескольких вебхуков

get

/gw/oauth2/webhooks/v1/status

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

statuses

array

Добавить еще поле

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

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

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

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

[...]

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

]

[{...}]

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

status: enum

[created, verification, active, removed, deactivated]

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

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

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

hook:{...}

Деактивированный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:{...}

Активный вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:{...}

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

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

verification:{...}

Проверка вебхука

status: enum

[progress, failed]

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

progress — Выполнение
failed — Провалена

fail_reason: enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

unknown_error — Неизвестная ошибка

Ошибка на стороне ATI.SU
tls_error — Ошибка установки защищенного соединения

Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS
socket_error — Ошибка создания TCP соединения

Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы
request_error — Ошибка запроса

Получен HTTP-код, отличный от 200, или превышено время ожидания ответа
challenge_mismatch — Challenge не совпадает
wrong_response_format — Неправильный формат ответа

Формат ответа отличается от JSON-строки

}

hook:{...}

Проверяемый вебхук

id: string

Идентификатор

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

Идентификатор контакта

key: string (nullable)

Ключ, используемый для подписывания запросов

}

}]

Загрузка...

Развернуть все Свернуть все

Загрузка...

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

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. В теле запроса передается одна или несколько обновленных сущностей (параметр entities[].entity) и другие параметры события.

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

Тело запроса

Развернуть все

Свернуть все

Пример

Модель

{...}

"topic":"orders",

"entities":[...],

{...}

"entity_id":"4ea8c372-9510-4880-a80d-fb9ac19129cf",

"action_date":"2021-04-30T05:12:41.687Z",

"entity":{...}

"id":"4ea8c372-9510-4880-a80d-fb9ac19129cf"

}

"is_retry":false

}

{...}

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

topic: string

Тема

entities:[{...}]

Сообщения

entity_id: string

Идентификатор отправляемой сущности

action_date: date-time

Дата события

entity: {missing-type-info} (nullable)

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

}]

is_retry: boolean

Является ли отправка повторной

}

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

POST /webhook?topic=orders HTTP/1.1
Host: example.org:443
Date: Thu, 01 Jan 1970 00:00:00 GMT
Digest: SypZnuCTiysyLuUz9DOYckaU/vf0zrzdxKL1j/sHemg=
Content-Type: application/json
Content-Length: 208
Authorization: HMAC-SHA-256 Credential=6447f577905114d5b9b2c618&SignedHeaders=Date;Digest;Host&Signature=V8CpKji2ysF5h5VVerhcq/GMQGxoHwf0EcGiDIL41e0=

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

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

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

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

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

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

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

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

Получить проваленные отправки

get

/webhooks/v1/distributions/failed/{id}

string

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

since

date-time

Начальная дата фильтра в формате ISO

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

[...]

{...}

"entity_id":"string",

"action_date":"1970-01-01T00:00:00.000Z",

"status":"failed",

"entity":null

}

]

[{...}]

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

entity_id: string

Идентификатор отправляемой сущности

action_date: date-time

Дата события

status: enum

[failed]

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

failed — Провалена

entity: {missing-type-info} (nullable)

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

}]

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 временно недоступна

string

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

since

date-time

Начальная дата фильтра в формате ISO

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

[...]

{...}

"entity_id":"string",

"action_date":"1970-01-01T00:00:00.000Z",

"status":"failed",

"entity":null

}

]

[{...}]

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

entity_id: string

Идентификатор отправляемой сущности

action_date: date-time

Дата события

status: enum

[failed]

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

failed — Провалена

entity: {missing-type-info} (nullable)

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

}]

4XX Ошибка запроса. Подробнее про ошибки API

Развернуть все Свернуть все

Пример

Модель

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Загрузка...

Развернуть все Свернуть все

Загрузка...

Редактирование вебхука

Изменение параметров вебхука не предусмотрено, но для тем подписки с фильтром возможно редактирование фильтра с помощью соответствующего метода. Изменение канала подписки невозможно.

Отредактировать параметры фильтра

put

/webhooks/v1/subscriptions/{id}

string

Id вебхука

Развернуть все Свернуть все

body

object

Параметры фильтра

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

Каналы подписки

cargoes.on_boards — Грузы на площадках
auctions.on_boards — Торги на площадках

boards: [string]

Идентификаторы площадок для подписки

boards: [string]

Идентификаторы площадок для подписки

}

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

Каналы подписки

cargoes.on_boards — Грузы на площадках
auctions.on_boards — Торги на площадках

boards: [string]

Идентификаторы площадок для подписки

boards: [string]

Идентификаторы площадок для подписки

}

Загрузка...

Развернуть все Свернуть все

Загрузка...

Отредактировать параметры фильтра

put

/gw/oauth2/webhooks/v1/subscriptions/{id}

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

string

Id вебхука

Развернуть все Свернуть все

body

object

Параметры фильтра

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

Каналы подписки

cargoes.on_boards — Грузы на площадках
auctions.on_boards — Торги на площадках

boards: [string]

Идентификаторы площадок для подписки

boards: [string]

Идентификаторы площадок для подписки

}

CURL

Копировать

Пример ответа

Ответ

200

Развернуть все Свернуть все

Пример

Модель

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

Каналы подписки

cargoes.on_boards — Грузы на площадках
auctions.on_boards — Торги на площадках

boards: [string]

Идентификаторы площадок для подписки

boards: [string]

Идентификаторы площадок для подписки

}

Загрузка...

Развернуть все Свернуть все

Загрузка...

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

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

Удалить вебхук

delete

/webhooks/v1/delete/{id}

string

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

CURL

Копировать

Пример ответа

Ответ

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 временно недоступна

string

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

CURL

Копировать

Пример ответа

Ответ

202

Развернуть все Свернуть все

4XX Ошибка запроса. Подробнее про ошибки API

Развернуть все Свернуть все

Пример

Модель

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Загрузка...

Развернуть все Свернуть все

Загрузка...

Вебхуки

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

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

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

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

3. TLS

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

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

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

Верификация

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

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

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

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

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

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

Редактирование вебхука

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