Подписка на вебхуки (Webhooks)

Методы предназначены для управления подпиской на получение вебхуков на URL клиента.

Так как тестовый аккаунт СДЭК является общим для всех клиентов, для тестирования вебхуков необходимо использовать только боевой URL СДЭК.
В запросе на добавление подписки укажите свой тестовый URL, куда будут приходить вебхуки. После завершения тестирования поменяйте его на свой боевой URL.

1. Добавление подписки

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

Запрос на добавление подписки

Для использования необходимо отправить POST-запрос на URL: https://api.cdek.ru/v2/webhooks

Тело запроса необходимо передавать в формате JSON (Content-Type: application/json).

Поддерживаются следующие поля:

№	Название поля	Описание	Тип поля	Обяз. для заполн.
1	url	URL, на который клиент хочет получать вебхуки	string()	да
2	type¹	Тип события: ORDER_STATUS - событие по статусам PRINT_FORM - готовность печатной формы DOWNLOAD_PHOTO - получение фото документов по заказам PREALERT_CLOSED - получение информации о закрытии преалерта	string()	да
3	retryable	Добавление возможности повторной отправки вебхука в случае ошибки (по умолчанию false)	boolean	нет
4	additional	Создание дополнительной подписки	boolean	нет

¹ Если у клиента уже есть подписка с указанным типом, то старый url перезатирается на новый

Ответ на добавление подписки

Ответ возвращается в формате JSON:

№	Название поля	Описание	Тип поля	Обяз. для заполн.
1	entity	Информация о подписке	entity	нет
1.1	uuid	Идентификатор подписки в ИС СДЭК	UUID	нет
1.2	retryable	Повторная отправка вебхука в случае ошибки. Если не был передан, то по умолчанию "false". Если был передан признак "additional = true" , то параметр "retryable" будет также "true".	boolean	да
2	requests	Информация о запросе над подпиской	request[]	да
2.1	request_uuid	Идентификатор запроса в ИС СДЭК	UUID	нет
2.2	type	Тип запроса Может принимать значения: CREATE, UPDATE, DELETE, AUTH, GET	string()	да
2.3	date_time	Дата и время установки текущего состояния запроса (формат yyyy-MM-dd'T'HH:mm:ssZ)	datetime	да
2.4	state	Текущее состояние запроса Может принимать значения: ACCEPTED - пройдена предварительная валидация и запрос принят WAITING - запрос ожидает обработки (зависит от выполнения другого запроса) SUCCESSFUL - запрос обработан успешно INVALID - запрос обработался с ошибкой	string()	да
2.5	errors	Ошибки, возникшие в ходе выполнения запроса	error[]	нет
2.5.1	code	Код ошибки	string()	да
2.5.2	message	Описание ошибки	string()	да
2.6	warnings	Предупреждения, возникшие в ходе выполнения запроса	warning[]	нет
2.6.1	code	Код предупреждения	string()	да
2.6.2	message	Описание предупреждения	string()	да

{ 
	"url":"https://webhook.site",
	"type":"ORDER_STATUS"
}

{
    "entity": {
        "uuid": "73c65d02-51a9-4423-8ee8-cc662ec3eb85"
    },
    "requests": [
        {
            "request_uuid": "72753031-0e1b-4f1d-abcc-b0bb0bd6ab2f",
            "type": "CREATE",
            "state": "SUCCESSFUL",
            "date_time": "2020-02-10T12:14:57+0000",
            "errors": [],
            "warnings": []
        }
    ]
}

2. Информация о подписке

Метод предназначен для получения информации о подписке/подписках клиента на получение вебхуков.

Запрос на получение информации о подписке

Для использования необходимо отправить GET-запрос на URL:

информация о подписке: https://api.cdek.ru/v2/webhooks/{uuid}, где uuid - идентификатор подписки
информация о всех текущих подписках: https://api.cdek.ru/v2/webhooks

Ответ на получение информации о подписке

Ответ возвращается в формате JSON:

№	Название поля	Описание	Тип поля	Обяз. для заполн.
1	entity	Информация о подписке	entity	нет
1.1	uuid	Идентификатор подписки	UUID	да
1.2	url	URL, на который клиенту приходят вебхуки	string()	да
1.3	type	Тип события	string()	да
2	requests	Информация о запросе над подпиской	request[]	да
2.1	request_uuid	Идентификатор запроса в ИС СДЭК	UUID	нет
2.2	type	Тип запроса Может принимать значения: CREATE, UPDATE, DELETE, AUTH, GET	string()	да
2.3	date_time	Дата и время установки текущего состояния запроса (формат yyyy-MM-dd'T'HH:mm:ssZ)	datetime	да
2.4	state	Текущее состояние запроса Может принимать значения: ACCEPTED - пройдена предварительная валидация и запрос принят WAITING - запрос ожидает обработки (зависит от выполнения другого запроса) SUCCESSFUL - запрос обработан успешно INVALID - запрос обработался с ошибкой	string()	да
2.5	errors	Ошибки, возникшие в ходе выполнения запроса	error[]	нет
2.5.1	code	Код ошибки	string()	да
2.5.2	message	Описание ошибки	string()	да
2.6	warnings	Предупреждения, возникшие в ходе выполнения запроса	warning[]	нет
2.6.1	code	Код предупреждения	string()	да
2.6.2	message	Описание предупреждения	string()	да

https://api.cdek.ru/v2/webhooks/73c65d02-51a9-4423-8ee8-cc662ec3eb85

{
    "entity": {
        "uuid": "73c65d02-51a9-4423-8ee8-cc662ec3eb85",
        "type": "ORDER_STATUS",
        "url": "https://webhook.site"
    },
    "requests": [
        {
            "request_uuid": "72753031-5ae3-448f-ba78-ea29d08e89fa",
            "type": "CREATE",
            "state": "SUCCESSFUL",
            "date_time": "2020-02-10T12:17:06+0000",
            "errors": [],
            "warnings": []
        }
    ]
}

Ответ на получение информации о всех текущих подписках

Ответ возвращается в формате JSON:

№	Название поля	Описание	Тип поля	Обяз. для заполн.
1.1	uuid	Идентификатор подписки	UUID	да
1.2	url	URL, на который клиенту приходят вебхуки	string()	да
1.3	type	Тип события	string()	да
1.4	requests	Информация о запросе	request[]	нет
1.4.1	type	Тип запроса Может принимать значения: CREATE, UPDATE, DELETE, AUTH, GET	string()	да
1.4.2	date_time	Дата и время установки текущего состояния запроса (формат yyyy-MM-dd'T'HH:mm:ssZ)	datetime	да
1.4.3	state	Текущее состояние запроса Может принимать значения: ACCEPTED - пройдена предварительная валидация и запрос принят WAITING - запрос ожидает обработки (зависит от выполнения другого запроса) SUCCESSFUL - запрос обработан успешно INVALID - запрос обработался с ошибкой	string()	да
1.4.4	errors	Ошибки, возникшие в ходе выполнения запроса	error[]	нет
1.4.4.1	code	Код ошибки	string()	да
1.4.4.2	message	Описание ошибки	string()	да
1.4.5	warnings	Предупреждения, возникшие в ходе выполнения запроса	warning[]	нет
1.4.5.1	code	Код предупреждения	string()	да
1.4.5.2	message	Описание предупреждения	string()	да

https://api.cdek.ru/v2/webhooks/

[
    {
        "type": "ORDER_STATUS",
        "uuid": "d7da1dbd-ae19-4f86-ab85-3274fa96ea8e",
        "url": "https://webhook.site/"
    },
    {
        "type": "PRINT_FORM",
        "uuid": "6624c7c0-680a-4c4e-9ed7-3f48ca9df4f4",
        "url": "https://webhook.site/"
    },
    {
        "type": "DOWNLOAD_PHOTO",
        "uuid": "41b9c676-bb54-4107-ba32-30ad4f1e9c7b",
        "url": "https://webhook.site/"
    },
    {
        "type": "PREALERT_CLOSED",
        "uuid": "0d15c501-8ed5-4f44-a462-ea7ec37cea22",
        "url": "https://webhook.site/"
    }
]

3. Удаление подписки

Метод предназначен для удаления подписки на получение вебхуков.

Запрос на удаление подписки

Для использования необходимо отправить DELETE-запрос на URL:
https://api.cdek.ru/v2/webhooks/{uuid}, где uuid - идентификатор подписки

Ответ на удаление подписки

Ответ возвращается в формате JSON:

№	Название поля	Описание	Тип поля	Обяз. для заполн.
1	entity	Информация о подписке	entity	нет
1.1	uuid	Идентификатор удаленной подписки	UUID	да
2	requests	Информация о запросе над подпиской	request[]	да
2.1	request_uuid	Идентификатор запроса в ИС СДЭК	UUID	нет
2.2	type	Тип запроса Может принимать значения: CREATE, UPDATE, DELETE, AUTH, GET	string()	да
2.3	date_time	Дата и время установки текущего состояния запроса (формат yyyy-MM-dd'T'HH:mm:ssZ)	datetime	да
2.4	state	Текущее состояние запроса Может принимать значения: ACCEPTED - пройдена предварительная валидация и запрос принят WAITING - запрос ожидает обработки (зависит от выполнения другого запроса) SUCCESSFUL - запрос обработан успешно INVALID - запрос обработался с ошибкой	string()	да
2.5	errors	Ошибки, возникшие в ходе выполнения запроса	error[]	нет
2.5.1	code	Код ошибки	string()	да
2.5.2	message	Описание ошибки	string()	да
2.6	warnings	Предупреждения, возникшие в ходе выполнения запроса	warning[]	нет
2.6.1	code	Код предупреждения	string()	да
2.6.2	message	Описание предупреждения	string()	да

https://api.cdek.ru/v2/webhooks/73c65d02-51a9-4423-8ee8-cc662ec3eb85

{
    "entity": {
        "uuid": "73c65d02-51a9-4423-8ee8-cc662ec3eb85"
    },
    "requests": [
        {
            "request_uuid": "72753031-0e1b-4f1d-abcc-b0bqw456ab2f",
            "type": "DELETE",
            "state": "SUCCESSFUL",
            "date_time": "2020-02-10T12:14:57+0000",
            "errors": [],
            "warnings": []
        }
    ]
}