Upload callback

Updated at：2025-11-03

Upload synchronous callback

API description

This API enables BOS to provide synchronous callbacks to the application server when a file (object) is uploaded. The application server corresponds to the callback address provided by the user.

The supported upload operations are as follows:

Normal upload (PutObject)
Complete multipart upload (CompleteMultipartUpload)

Request syntax (Request)

Plain Text

1PUT /<ObjectName> HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <Date>
4Authorization: <AuthorizationString>
5Content-Type: text/plain
6Content-Length: <Content_Length>
7x-bce-process: <callback_command>

Request parameters
Refer to the description in the "Request Header Fields" section.
Request headers

Name	Types	Description	Required or not
x-bce-process	string	The x-bce-process parameter is used to store callback commands. These can be included either in the query string or in the header. For detailed usage, refer to the "Instructions for Use of x-bce-process" section below.	No

Format of the x-bce-process command

Plain Text

1x-bce-process: callback/callback,${key}_${value},${key}_${value}

Description of the x-bce-process parameter:

Parameter name	Abbreviation	Types	Value range	Description	Required or not
urls	u	string	-	The address list encoded with Base64 for url security has a maximum of 3 addresses. The specific content is a JSON array: `["http://test1.com/callback", "http://test2.com/callback"]`	Yes
mode	m	string	`sync`	Currently, it can only be synchronous. If not set, the default value is `sync`	No
vars	v	string	-	Any custom parameters passed during the callback must not exceed 1,024 bytes in length. It is recommended to encode such data with Base64.	No
encrypt	e	string	`config`	The available options for the encryption type of the callback signature are as follows: `config`: Indicates that the signature key for callback requests is configured by creating event notification rules.	No
key	k	string	-	The available values for key for callback signature are as follows: If "encrypt" is set to "config," it indicates that the signature key for callback requests is configured through event notification rules, and the value corresponds to the ID of the specific event notification rule.	No

Instruction for use of the x-bce-process parameter:

The sub-command for x-bce-process callback is callback, and the parameters are abbreviated;
If multiple URL callback addresses are provided in a single request, the callback process will stop once the first callback is successful, and subsequent URLs will not be invoked.
Callback information is returned in the JSON body.
The parameters "encrypt" and "key" are only applicable when setting callback signatures, as detailed in the section below.

Response

Response element

The response elements are identical to those of the PutObject and CompleteMultipartUpload APIs.

If the synchronous callback is successful and the user’s application server responds with content, a "callback" field will be added to the response elements to store the application server’s response. This content will then be returned to the client.

Name	Types	Description
callback	object	An object containing the response content from the user's application server
+result	string	Response content from the user's application server

Callback:

If the user’s application server returns a StatusCode of 200, the callback is considered successful, and the process is terminated. For any other errors or if there is no response, the next URL will be retried.
If all URL callbacks fail, the callback is considered unsuccessful, and an error status code of 203 is returned. This indicates that the file has been successfully uploaded to BOS, but the callback failed. A callback failure only signifies that BOS did not receive the expected callback response and does not imply that the application server did not receive the callback request.
When the callback succeeds, the return value from the application server must not exceed 1 MB. Otherwise, the callback will fail, and an error message "PayloadTooLarge" will be returned.
If the original CompleteMultipartUpload API already includes a response body, the callbackResult will be appended to the original returned JSON.
In the event of a callback failure, the failure reason will be included in the code and message fields.

Callback request format

The request format for synchronous upload callback application services aligns with the callback format used in bucket event notifications.

For example, if the callback address planned by the user is ["https://www.test.com/callback"], its value after Base64 encoding is "WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd". If the custom parameter content planned by the user is {"key1":"value1"}, its value after base64 encoding is "eyJrZXkxIjoidmFsdWUxIn0=".

Assuming that when a user uploads a request, the header carries the following callback command:

Plain Text

1x-bce-process: callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd,v_eyJrZXkxIjoidmFsdWUxIn0=

An example of a URL callback request sent to the user’s application server is shown below, where the "Authorization" signature is optional.

Plain Text

1POST /<callback_url> HTTP/1.1
2Host: <User_Host>
3Date: <Date>
4Content-Type: application/json; charset=utf-8
5Authorization: <AuthorizationString>
6Content-Length: <Content_Length>
7{
8    "events": [
9        {
10            "version": "1.0",
11            "eventId": "2a513199-bbb9-4ac7-b12a-60213c26810d",
12            "eventOrigin": "bos:callback",
13            "eventTime": "2023-09-05T02:28:49Z",
14            "eventSource": "bos:callback",
15            "eventType": "PutObject",
16            "eventFrom": "Client",
17            "content": {
18                "userId": "abcdefgh12345678a4ffa3b2ececa17f",
19                "ownerId": "abcdefgh12345678a4ffa3b2ececa17f",
20                "accessKeyId": "*****************************",
21                "domain": "bj.bcebos.com",
22                "bucket": "bucket-test",
23                "object": "object-test",
24                "etag": "977b9623a15e520c663ac5ff6647e881",
25                "contentType": "application/octet-stream",
26                "filesize": 24414,
27                "lastModified": "2018-09-05T02:28:49Z",
28                "storageClass": "STANDARD",
29                "xVars": "eyJrZXkxIjoidmFsdWUxIn0="
30            }
31        }
32    ]
33}

Callback signature (optional)

Once the user configures the x-bce-process synchronous request callback parameters, the BOS server will send a POST callback request to the user’s application server based on the user-configured callback URL. After receiving the callback request, if the application server needs to verify that the callback request was indeed initiated by BOS, it can validate the BOS identity through the signature included in the callback.

Callback security is ensured using Baidu AI Cloud’s IAM signature algorithm, as detailed in the IAM signature algorithm documentation.

The signature process consists of three steps:

(1) Configure the key in advance by creating an event notification rule. Users can set this up via the console or SDK.

For example, the ID of the created event notification rule is "callback1", where the key is the key set by the user. It a length of 32 characters and can only contain digits [0-9] and lowercase letters.

Plain Text

1PUT /?notification HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <Date>
4Authorization: <Authorization_String>
5Content-Type: application/json; charset=utf-8
6Content-Length: <Content_Length>
7{
8    "notifications": [
9        {
10            "id": "callback1",
11            "encryption": {
12                "key": "12345678abcdefgh9d1aff8bc436a2f6"
13            }
14        }
15    ]
16}

(2) In the file upload request, carry the callback command containing encryption parameters. For example, if the callback address planned by the user is ["https://www.test.com/callback"], its value after Base64 encoding is "WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd".

Plain Text

1x-bce-process: callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd,e_config,k_callback1,

(3) The BOS server initiates a signed callback to the user's application server. The AK used to calculate the signature is the AK from the user's current request (it defaults to "-" if no signature is provided), and the SK is the key configured by the user in the first step. The signature generated is located in the request header "Authorization".

Example

Request example
For example, if the callback address planned by the user is ["https://www.test.com/callback"], its value after Base64 encoding is "WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd".

Attached in the Header:

Plain Text

1PUT /<ObjectName> HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <Date>
4Authorization: <AuthorizationString>
5Content-Type: text/plain
6Content-Length: <Content_Length>
7x-bce-process: callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd

Attached in the query:

Plain Text

1http://<BucketName>.bj.bcebos.com/image.png?x-bce-process=callback/callback,u_WyJodHRwczovL3d3dy50ZXN0LmNvbS9jYWxsYmFjayJd

PutObject response example

After the callback, the callback result will be returned to the client with the following format:

Plain Text

1HTTP/1.1 200 OK
2Date: Wed, 06 Apr 2016 06:34:40 GMT
3ETag: "1b2cf535f27731c974343645a3985328"
4Content-Length: 22
5Connection: close
6Server: BceBos
7{
8    "callback": {
9        "result": "${callback_result}"
10    }
11}

CompleteMultipartUpload response example

Plain Text

1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Connection: close
5Server: BceBos
6{
7	"location":"http://bj.bcebos.com/BucketName/ObjectName",
8	"bucket":"BucketName",
9	"key":"object",
10	"eTag":"3858f62230ac3c915f300c664312c11f",
11    "callback": {
12        "result": "${callback_result}"
13    }
14}

Error code

Service-Related Interface