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 - order status events PRINT_FORM - print forms readiness DOWNLOAD_PHOTO - receiving photo documents for orders	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+0700",
            "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+0700",
            "errors": [],
            "warnings": []
        }
    ]
}

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/print/orders/72753031-d302-48c5-8219-f3bb2a4b1f7b

{
    "entity": {
        "uuid": "72753031-d302-48c5-8219-f3bb2a4b1f7b",
        "orders": [
            {
                "order_uuid": "72753031-ebf7-4f15-8d23-dc6951808d69"
            }
        ],
        "copy_count": 2,
        "statuses": [
            {
                "code": "ACCEPTED",
                "name": "Принят",
                "date_time": "2020-02-10T12:26:11+0700"
            },
            {
                "code": "PROCESSING",
                "name": "Формируется",
                "date_time": "2020-02-10T12:26:11+0700"
            }
        ],
        "errors": [],
        "warnings": []
    },
    "requests": [
        {
            "errors": [],
            "warnings": []
        }
    ]
}}

The methods are used to manage the subscription of webhooks to be sent to the client's 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 - order status events PRINT_FORM - print forms readiness	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+0700",
            "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, WAITING, SUCCESSFUL, INVALID	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+0700",
            "errors": [],
            "warnings": []
        }
    ]
}

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/print/orders/72753031-d302-48c5-8219-f3bb2a4b1f7b

{
    "entity": {
        "uuid": "72753031-d302-48c5-8219-f3bb2a4b1f7b",
        "orders": [
            {
                "order_uuid": "72753031-ebf7-4f15-8d23-dc6951808d69"
            }
        ],
        "copy_count": 2,
        "statuses": [
            {
                "code": "ACCEPTED",
                "name": "Принят",
                "date_time": "2020-02-10T12:26:11+0700"
            },
            {
                "code": "PROCESSING",
                "name": "Формируется",
                "date_time": "2020-02-10T12:26:11+0700"
            }
        ],
        "errors": [],
        "warnings": []
    },
    "requests": [
        {
            "errors": [],
            "warnings": []
        }
    ]
}}