b2_set_bucket_notification_rules
  • 19 Oct 2026
  • Dark
    Light

b2_set_bucket_notification_rules

  • Dark
    Light

Article summary

Post
/b2api/v4/b2_set_bucket_notification_rules

Modifies bucket event notification rules

Replace the event notification rules of an existing bucket. Webhook delivery attempts to the configured target URL are metered as Class D transactions.

Header parameters
Authorization
stringRequired

An account authorization token, obtained from b2_authorize_account.

The token must have the writeBucketNotifications capability.

Body parameters
Bucket Notification Rules Request
[
  {
    "bucketId": "aea8c5bc362ae55070130333",
    "eventNotificationRules": [
      {
        "eventTypes": [
          "b2:ObjectCreated:Upload",
          "b2:ObjectCreated:MultipartUpload"
        ],
        "isEnabled": true,
        "name": "mySampleRule1",
        "objectNamePrefix": "",
        "targetConfiguration": {
          "customHeaders": [
            {
              "name": "X-My-Custom-Header-1",
              "value": "myCustomHeaderVal1"
            },
            {
              "name": "X-My-Custom-Header-2",
              "value": "myCustomHeaderVal2"
            }
          ],
          "hmacSha256SigningSecret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0",
          "targetType": "webhook",
          "url": "https://www.example.com/sampleurl"
        }
      }
    ]
  }
]
Expand All
object
bucketId
string Required

The unique identifier for the bucket containing the event notification rules.

Exampleaea8c5bc362ae55070130333
eventNotificationRules
Array of object Required

An array containing event notification rules.

The event notification rules in this array replace the bucket’s existing rules.

object
eventTypes
Array of string Required

The list of event types for the event notification rule.

Example[ "b2:ObjectCreated:Upload", "b2:ObjectCreated:MultipartUpload" ]
string
isEnabled
boolean Required

Whether the event notification rule is enabled.

Exampletrue
isSuspended
boolean

Whether the event notification rule is suspended. This is ignored by b2_set_bucket_notification_rules.

Exampletrue
name
string Required

A name for the event notification rule. The name must be unique among the bucket's notification rules.

ExamplemySampleRule1
objectNamePrefix
string Required

Specifies which object(s) in the bucket the event notification rule applies to. The objectNamePrefix must not overlap with another objectNamePrefix for the same event type.

For example, an event notification rule with the prefix "images/pets/" is not allowed if there is another notification rule in the list of the same event type with "images/".

Exampleimages/
suspensionReason
string

A brief description of why the event notification rule was suspended. This is ignored by b2_set_bucket_notification_rules.

ExampleA reason for suspension
targetConfiguration
object Required

The target configuration for the event notification rule.

This object will always contain the targetType field. Currently, the only valid value for targetType is "webhook."

The fields for "webhook" objects are defined below. However, other targetType values and collections of fields will be available in the future.

Example{ "customHeaders": [ { "name": "myCustomHeader1", "value": "myCustomHeaderVal1" }, { "name": "myCustomHeader2", "value": "myCustomHeaderVal2" } ], "hmacSha256SigningSecret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0", "targetType": "webhook", "url": "https://www.example.com/sampleurl" }
customHeaders
Array of object

When present, additional header name/value pairs to be sent on the webhook invocation. There can be at most 10 custom header name/value pairs.

The total number of URL-encoded bytes must not exceed 2,048. Each custom header name/value pair will have three extra bytes added to the total, accounting for the :, \r, and \n characters. You may not use a custom header name that begins with X-Bz-.

Example[ { "name": "myCustomHeader1", "value": "myCustomHeaderVal1" } ]
object
name
string

The name of the header.

Examplemy-custom-header-name
value
string

The value of the header

Examplemy-custom-header-value
hmacSha256SigningSecret
string

If non-null, this is used to sign the webhook's contents. The value for this field must be a 32-character alphanumeric string.

ExampleMTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0
maxEventsPerBatch
integer

Represents the maximum number of events a user will receive per webhook invocation. The value must be a number between 1 and 50. The default value is 1.

Example1
targetType
string Required

The type of the target configuration, currently "webhook" only.

Examplewebhook
url
string Required

The URL for the webhook. The URL must include the HTTPS protocol and must not point to a Backblaze hostname or IP address.

Examplehttps://www.example.com
Responses
200

The request succeeded.

Bucket Notification Rules Response
[
  {
    "bucketId": "aea8c5bc362ae55070130333",
    "eventNotificationRules": [
      {
        "eventTypes": [
          "b2:ObjectCreated:Upload",
          "b2:ObjectCreated:MultipartUpload"
        ],
        "isEnabled": true,
        "isSuspended": false,
        "name": "mySampleRule1",
        "objectNamePrefix": "",
        "suspensionReason": "",
        "targetConfiguration": {
          "customHeaders": [
            {
              "name": "X-My-Custom-Header-1",
              "value": "myCustomHeaderVal1"
            },
            {
              "name": "X-My-Custom-Header-2",
              "value": "myCustomHeaderVal2"
            }
          ],
          "hmacSha256SigningSecret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0",
          "targetType": "webhook",
          "url": "https://www.example.com/sampleurl"
        }
      }
    ]
  }
]
Expand All
object
bucketId
string

The unique identifier for the bucket containing the event notification rules.

Exampleaea8c5bc362ae55070130333
eventNotificationRules
Array of object

An array of Event Notification Rules.

Example[ { "eventTypes": [ "b2:ObjectCreated:Upload", "b2:ObjectCreated:MultipartUpload" ], "isEnabled": true, "isSuspended": false, "name": "mySampleRule1", "objectNamePrefix": "", "suspensionReason": "", "targetConfiguration": { "customHeaders": [ { "name": "myCustomHeader1", "value": "myCustomHeaderVal1" }, { "name": "myCustomHeader2", "value": "myCustomHeaderVal2" } ], "hmacSha256SigningSecret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0", "maxEventsPerBatch": 1, "targetType": "webhook", "url": "https://www.example.com/sampleurl" } } ]
object
eventTypes
Array of string

The list of event types for the event notification rule.

Example[ "b2:ObjectCreated:*" ]
string
isEnabled
boolean

Whether the event notification rule is enabled.

Exampletrue
isSuspended
boolean

Whether the event notification rule is suspended.

Exampletrue
name
string

A name for the event notification rule. The name must be unique among the bucket's notification rules.

ExamplemySampleRule1
objectNamePrefix
string

Specifies which object(s) in the bucket the event notification rule applies to.

Exampleimages/
suspensionReason
string

A brief description of why the event notification rule was suspended.

ExampleA reason for suspension
targetConfiguration
object

The target configuration for the event notification rule.

This object will always contain the targetType field. Currently, the only valid value for targetType is "webhook."

The fields for "webhook" objects are defined below. However, other targetType values and collections of fields will be available in the future.

Example{ "customHeaders": [ { "name": "myCustomHeader1", "value": "myCustomHeaderVal1" }, { "name": "myCustomHeader2", "value": "myCustomHeaderVal2" } ], "hmacSha256SigningSecret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0", "targetType": "webhook", "url": "https://www.example.com/sampleurl" }
customHeaders
Array of object

When present, additional header name/value pairs to be sent on the webhook invocation.

Example[ { "name": "myCustomHeader1", "value": "myCustomHeaderVal1" } ]
object
name
string

The name of the header.

Examplemy-custom-header-name
value
string

The value of the header

Examplemy-custom-header-value
hmacSha256SigningSecret
string

The signing secret for use in verifying the X-Bz-Event-Notification-Signature.

ExampleMTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0
maxEventsPerBatch
integer

Represents the maximum number of events a user will receive per webhook invocation. The value must be a number between 1 and 50. The default value is 1.

Example1
targetType
string

The type of the target configuration, currently "webhook" only.

Examplewebhook
url
string

The URL for the webhook.

Examplehttps://www.example.com
400
statuscodedescription
400bad_requestbucketId is not valid.
400cannot_edit_suspended_ruleSuspended rules cannot be edited, only deleted.
400custom_header_name_conflictThere must not be more than one custom header in an event notification rule with the same header name.
400custom_header_name_disallowedThe custom header name supplied is not allowed.
400custom_header_name_emptyEach custom header name must be a non-empty String.
400custom_header_name_invalidA custom header name is invalid.
400custom_header_size_invalidThe total size of URL encoded custom header name/value bytes must not exceed 2,048.
400custom_header_value_invalidA custom header value is invalid.
400event_type_categoriesAn event notification rule has event types from multiple categories.
400event_type_invalidAn event type is invalid.
400event_type_overlapAn event notification rule has overlap in the event types.
400event_types_emptyAn event notification rule has overlap in the event types.
400prefix_overlapMore than one event notification rule has overlap in the objectNamePrefix for the same event type.
400signing_secret_invalidThe signing secret provided is not allowed.
400rule_name_invalidAn event notification rule has an invalid rule name.
400target_url_domain_invalidThere must not be a webhook URL that points to a Backblaze domain.
400target_url_invalidThe target URL for an event notification rule is invalid.
400target_url_protocol_invalidThe target URL for an event notification rule is not using https.
400too_many_custom_headersAn event notification rule has more than 10 custom header name/value pairs.
400too_many_event_notification_rulesThere are more than 25 event notification rules defined.
object
status
integer

The numeric HTTP status code. Always matches the status in the HTTP response.

Example400
code
string

A single-identifier code that identifies the error.

Exampleinvalid_bucket_name
message
string

A human-readable message, in English, saying what went wrong.

Examplebucket name is too long
401
statuscodedescription
401bad_auth_tokenThe auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.
401expired_auth_tokenThe auth token used has expired. Call b2_authorize_account again to get a new one.
401unauthorizedThe auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account.
403
statuscodedescription
403transaction_cap_exceededTransaction cap exceeded. Daily transaction caps apply to non-paying accounts. To view or adjust your caps, sign in to your B2 Cloud Storage account online and select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar.

Was this article helpful?