All Products
Search

This Product

    Object Storage Service:Upload callbacks (Ruby SDK)

    Document Center

    Object Storage Service:Upload callbacks (Ruby SDK)

    Last Updated:Mar 20, 2026

    After an object is uploaded, Object Storage Service (OSS) can send an HTTP POST request to your application server. Use upload callbacks to trigger server-side processing — such as updating a database record or starting a media transcoding job — immediately after a successful upload.

    How it works

    1. Configure a callback when submitting the upload request. Specify the callback URL, query parameters, and request body.

    2. OSS uploads the object. On success, OSS sends an HTTP POST request to your callback URL with the body you specified.

    3. If the callback request fails, the SDK raises a CallbackError on the client side.

    Usage notes

    • Upload callbacks are supported only for put_object and resumable_upload.

    • The callback URL cannot contain a query string. Pass query parameters in the :query option instead.

    • If the upload succeeds but the callback fails, the SDK raises Aliyun::OSS::CallbackError. To ignore the error, rescue the exception explicitly.

    • For a reference implementation of the callback server, see callback_server.rb.

    Configure an upload callback

    Both put_object and resumable_upload accept a callback: option. The callback object takes three parameters:

    ParameterDescriptionExample
    urlThe URL that OSS sends the HTTP POST request tohttp://oss-demo.aliyuncs.com:23450
    queryQuery parameters appended to the callback request. Do not include these in url.{user: 'put_object'}
    bodyThe POST body sent to your callback server. Use ${bucket} and ${object} to include the bucket name and object key in the body.'bucket=${bucket}&object=${object}'

    Use put_object with a callback

    require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  # Replace with the endpoint for your region.
  # The China (Hangzhou) region is used in this example.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Read AccessKey credentials from environment variables.
  # Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
  access_key_id: ENV['OSS_ACCESS_KEY_ID'],
  access_key_secret: ENV['OSS_ACCESS_KEY_SECRET']
)

bucket = client.get_bucket('examplebucket')

callback = Aliyun::OSS::Callback.new(
  url: 'http://oss-demo.aliyuncs.com:23450',
  query: {user: 'put_object'},
  body: 'bucket=${bucket}&object=${object}'
)

begin
  bucket.put_object('files/hello', file: '/tmp/x', callback: callback)
rescue Aliyun::OSS::CallbackError => e
  puts "Callback failed: #{e.message}"
end

    Use resumable_upload with a callback

    The callback configuration is identical to put_object. Pass the same callback: option to resumable_upload.

    require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  # Replace with the endpoint for your region.
  # The China (Hangzhou) region is used in this example.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Read AccessKey credentials from environment variables.
  # Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
  access_key_id: ENV['OSS_ACCESS_KEY_ID'],
  access_key_secret: ENV['OSS_ACCESS_KEY_SECRET']
)

bucket = client.get_bucket('examplebucket')

callback = Aliyun::OSS::Callback.new(
  url: 'http://oss-demo.aliyuncs.com:23450',
  query: {user: 'put_object'},
  body: 'bucket=${bucket}&object=${object}'
)

begin
  bucket.resumable_upload('files/hello', '/tmp/x', callback: callback)
rescue Aliyun::OSS::CallbackError => e
  puts "Callback failed: #{e.message}"
end

    What's next