Webhook Subscription

The methods are used to manage the subscription of webhooks to be sent to the client's URL.

Since the CDEK test account is common for all clients, only production CDEK URL should be used for testing the webhooks.
Specify your test URL to which the webhooks are to be sent, in your request for subscription. After completion of the testing, change it to your production URL.

1.Adding the Subscription

The method is used to add the webhook subscription.
At present, you can subscribe for order status events and print forms readiness.

Request for Adding the Subscription

In order to use this process, a POST request should be sent to URL: https://api.cdek.ru/v2/webhooks.

The request body should be sent in the JSON format (Content-Type: application/json).

The following fields are supported:

No.	Field name	Description	Field type	Mandatory (yes/no)
1	url	URL to which the client wants to receive webhooks	string()	yes
2	type¹	Event Type: ORDER_STATUS - event by statuses PRINT_FORM - readiness of printed form DOWNLOAD_PHOTO - receiving photo documents on orders PREALERT_CLOSED - receiving information about prealert closing	string()	yes

¹ If the client already has a subscription with the specified type, the previous url will be changed to a new one.

Response to the Request for Adding the Subscription

The response body is returned in the JSON format:

No.	Field name	Description	Field type	Mandatory (yes/no)
1	entity	Data of the subscription over which request is sent		no
1.1	uuid	Subscription identifier	UUID	yes
2	requests	Data on the request/requests over the subscription	request[]	yes
2.1	request_uuid	Subscription identifier in CDEK information system	UUID	no
2.2	type	Request type May take on values: CREATE, UPDATE, DELETE, AUTH, GET	string()	yes
2.3	state	Current status of the request May take on values: ACCEPTED - pre-validation passed and request accepted WAITING - the request is awaiting processing (depends on the execution of another request) SUCCESSFUL - the request was processed successfully INVALID - the request was processed with an error	string()	yes
2.4	date_time	Date and time of setting current status of the request (format yyyy-MM-dd'T'HH:mm:ssZ)	datetime	yes
2.5	errors	Request processing errors	error[]	no
2.5.1	code	Error code	string()	yes
2.5.2	message	Error description	string()	yes
2.6	warnings	Request processing warnings	warning[]	no
2.6.1	code	Warning code	string()	yes
2.6.2	message	Warning description	string()	yes

{
    "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. Details of Subscription

The method is used to get details of client's webhook subscription(-s).

Request for Details of Subscription

In order to use this process, a GET request should be sent to URL:

details of Subscription: https://api.cdek.ru/v2/webhooks/{uuid}, where uuid is the subscription identifier
details of all current subscriptions: https://api.cdek.ru/v2/webhooks

Response to the Request for Details of Subscription

The response body is returned in the JSON format:

No.	Field name	Description	Field type	Mandatory (yes/no)
1	entity	Data of the subscription over which request is sent		no
1.1	uuid	Subscription identifier	UUID	yes
1.2	url	URL to which webhooks are sent for the client	string()	yes
1.3	type	Event type	string()	yes
2	requests	Data on the request/requests over the subscription	request[]	yes
2.1	request_uuid	Subscription identifier in CDEK information system	UUID	no
2.2	type	Request type May take on values: CREATE, UPDATE, DELETE, AUTH, GET	string()	yes
2.3	state	Current status of the request May take on values: ACCEPTED - pre-validation passed and request accepted WAITING - the request is awaiting processing (depends on the execution of another request) SUCCESSFUL - the request was processed successfully INVALID - the request was processed with an error	string()	yes
2.4	date_time	Date and time of setting current status of the request (format yyyy-MM-dd'T'HH:mm:ssZ)	datetime	yes
2.5	errors	Request processing errors	error[]	no
2.5.1	code	Error code	string()	yes
2.5.2	message	Error description	string()	yes
2.6	warnings	Request processing warnings	warning[]	no
2.6.1	code	Warning code	string()	yes
2.6.2	message	Warning description	string()	yes

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": []
        }
    ]
}

Response to retrieve information about all current subscriptions.
The response is returned in JSON format:

Response to retrieve information about all current subscriptions.

The response is returnes in JSON format:

№	Field name	Description	Field type	Mandatory
1.1	uuid	Subscription ID	UUID	да
1.2	url	URL to which the client receives webhooks	string()	да
1.3	type	Event Type	string()	да
1.4	requests	Request information	request[]	нет
1.4.1	type	Request type. Can take the following values: CREATE, UPDATE, DELETE, AUTH, GET	string()	да
1.4.2	date_time	Date and time to set the current request state (format yyyy-MM-dd'T'HH:mm:ssZ)	datetime	да
1.4.3	state	Current state of the requestCan take the following values: ACCEPTED - preliminary validation has been passed and the request is acceptedWAITING - the request is waiting for processing (depends on the execution of another request)SUCCESSFUL - the request has been processed successfullyINVALID - the request has been processed with an error.	string()	да
1.4.4	errors	Errors that occurred during the query execution	error[]	нет
1.4.4.1	code	Error code	string()	да
1.4.4.2	message	Error description	string()	да
1.4.5	warnings	Warnings that occurred during query execution	warning[]	нет
1.4.5.1	code	Warning code	string()	да
1.4.5.2	message	Warning description	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. Deleting the Subscription

The method is used to delete the webhook subscription.

Request for Deleting the Subscription

In order to use this process, a DELETE request should be sent to URL:

https://api.cdek.ru/v2/webhooks/{uuid}, where uuid is the subscription identifier

Response to the Request for Deleting the Subscription

The response body is returned in the JSON format:

No.	Field name	Description	Field type	Mandatory (yes/no)
1	entity	Data of the subscription over which request is sent		no
1.1	uuid	Identifier of the deleted subscription	UUID	yes
2	requests	Data on the request/requests over the subscription	request[]	yes
2.1	request_uuid	Subscription identifier in CDEK information system	UUID	no
2.2	type	Request type May take on values: CREATE, UPDATE, DELETE, AUTH, GET	string()	yes
2.3	state	Current status of the request May take on values: ACCEPTED - pre-validation passed and request accepted WAITING - the request is awaiting processing (depends on the execution of another request) SUCCESSFUL - the request was processed successfully INVALID - the request was processed with an error	string()	yes
2.4	date_time	Date and time of setting current status of the request (format yyyy-MM-dd'T'HH:mm:ssZ)	datetime	yes
2.5	errors	Request processing errors	error[]	no
2.5.1	code	Error code	string()	yes
2.5.2	message	Error description	string()	yes
2.6	warnings	Request processing warnings	warning[]	no
2.6.1	code	Warning code	string()	yes
2.6.2	message	Warning description	string()	yes

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": []
        }
    ]
}

Webhook Subscription

1.Adding the Subscription

Request for Adding the Subscription

Response to the Request for Adding the Subscription

2. Details of Subscription

Request for Details of Subscription

Response to the Request for Details of Subscription

Response to retrieve information about all current subscriptions.The response is returned in JSON format:

Response to retrieve information about all current subscriptions.

3. Deleting the Subscription

Request for Deleting the Subscription

Response to the Request for Deleting the Subscription

Response to retrieve information about all current subscriptions.
The response is returned in JSON format: