Callback requests and responses

Request body

Each callback request sent by API Callback Gateway includes the following fields that must be processed by the callback handler:

Field

Type

Description

type

string

An identifier of the callback request. The callback handler can verify whether this identifier matches the one defined for this callback. Example: cti.a.p.acgw.request.v1.0~vendor.app.read_users.v1.0.

request_id

string

A UUID of the request.

created_at

string

A date in RFC3339 format when the request was made.

context

object

An object containing the information about the context of the request.

context.callback_id

string

An identifier of the callback. The callback handler must use this identifier to identify which action needs to be done and which responses can be provided. Example: cti.a.p.acgw.callback.v1.0~vendor.app.read_users.v1.0.

context.endpoint_id

string

An identifier of the endpoint. The callback handler can use this identifier to verify whether the request was intended for the endpoint where it is located.

context.tenant_id

string

An identifier of the tenant ID from which the request was made.

context.datacenter_url

string

The URL of Acronis data center from which the request was made.

payload

object

An object containing the data structure specified for the callback request. Optional if not specified.

Response body

Each callback response sent by the callback handler must include the following fields:

Field

Type

Description

type

string

An identifier of the callback response. The response identifier must match one of the identifiers defined for this callback. Example: cti.a.p.acgw.response.v1.0~vendor.app.read_users_ok.v1.0.

request_id

string

A UUID of the request that corresponds to this response.

response_id

string

A UUID of the response.

payload

object

An object containing the data structure configured for the callback response. Optional if not specified.

Request headers

To successfully process the requests coming from API Callback Gateway, the callback handler must check the following headers that are sent with each request:

Header

Description

X-CyberApp-Auth

An authentication header containing the base64-encoded credentials from ISV’s cloud. The credentials format is <identity>:<secrets>, where <identity> is an identity registered in the ISV’s service (such as a username, API client ID, etc.) in plain text format and <secrets> is a JSON text (such as {"<model_property>": <value>}) containing secrets (such as passwords, private keys, etc.) that are used to authenticate the identity. See UI builder for more details.

X-CyberApp-Extra

A header containing extra data specified by the ISV. The data is formatted as a base64-encoded JSON text. For example, if extra data was not provided, the header will contain the e30= base64-encoded string, which is decoded to the {} JSON string and can be parsed with a JSON parser.

Default error handling

While callbacks may define their own error responses, the API Callback Gateway provides default handling for specific HTTP error response codes and communication errors.

Default error response codes

The following HTTP status codes do not need to be specified in the callbacks and will be processed by the API Callback Gateway. A corresponding error message will also be rendered in the user interface for MSPs and end customers:

HTTP code

Description

UI message

401 Unauthorized

Callback handler rejected the unauthorized request.

Connection to <application_name> service could not be established due to invalid credentials.

403 Forbidden

Callback handler rejected the request due to invalid credentials.

Connection to <application_name> service could not be established due to invalid credentials.

410 Gone

Callback handler is no longer available at the provided URL.

Response from to <application_name> service cannot be processed due to invalid format.

429 Too Many Requests

Callback handler rejected the request due to too many requests. The request can be retried by API Callback Gateway.

-

500-599

Callback handler responded with an error that indicates a server error.

Connection to <application_name> service could not be established.

Where <application_name> is your CyberApp name.

Communication errors

The following communication errors will be handled by the API Callback Gateway and a corresponding error message will be rendered in the user interface for MSPs and End Customers:

Error

Description

UI message

TLS handshake failed

API Callback Gateway was unable to negotiate the secure protocol with the callback handler.

Connection to <application_name> service could not be established.

Invalid SSL certificate

API Callback Gateway was unable to verify the SSL certificate of the callback handler domain name.

Connection to <application_name> service could not be established due to invalid certificate.

Server is unreachable

API Callback Gateway was unable to find a route to the callback handler. The request can be retried by API Callback Gateway.

Connection to <application_name> service could not be established.

Connection timed out

API Callback Gateway was able to establish the connection but did not receive a response within the specific time. The request can be retried by API Callback Gateway.

Connection to <application_name> service could not be established.

Unexpected 2xx-3xx response

Callback handler responded with a response within the 200-399 range that does not match any code defined for this callback.

Response from to <application_name> service cannot be processed due to invalid format.

Unexpected 4xx response

Callback handler responded with a response within the 400-499 range that does not match any code defined for this callback or in the Status codes table.

Response from to <application_name> service cannot be processed due to invalid format.

Response schema error

Callback handler responded with a structure that does not match the schema defined for this callback.

Response from to <application_name> service cannot be processed due to invalid format.

Request schema error

Callback handler received a request from the user interface which structure does not match the schema defined for this callback.

Request to <application_name> was not sent due to invalid format.

Where <application_name> is your application name.