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
Authorization	An authorization header containing a JWT (JSON Web Token) signed by Acronis. The value format is `Bearer <jwt>`, where `<jwt>` is the JWT. See Request verification for more details.
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.