b2_set_bucket_notification_rules

Print
Dark
Light

b2_set_bucket_notification_rules

Print
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/b2api/v3/b2_set_bucket_notification_rules

Modifies bucket event notification rules

Replace the event notification rules of an existing bucket.

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

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

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

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, "maxEventsPerBatch": 1, "name": "mySampleRule1", "objectNamePrefix": "", "suspensionReason": "", "targetConfiguration": { "customHeaders": [ { "name": "myCustomHeader1", "value": "myCustomHeaderVal1" }, { "name": "myCustomHeader2", "value": "myCustomHeaderVal2" } ], "hmacSha256SigningSecret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0", "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

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

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.

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

targetType

string

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

Examplewebhook

url

string

The URL for the webhook.

Examplehttps://www.example.com

400

status	code	description
400	bad_request	`bucketId` is not valid.
400	cannot_edit_suspended_rule	Suspended rules cannot be edited, only deleted.
400	custom_header_name_conflict	There must not be more than one custom header in an event notification rule with the same header name.
400	custom_header_name_disallowed	The custom header name supplied is not allowed.
400	custom_header_name_empty	Each custom header name must be a non-empty String.
400	custom_header_name_invalid	A custom header name is invalid.
400	custom_header_size_invalid	The total size of URL encoded custom header name/value bytes must not exceed 2,048.
400	custom_header_value_invalid	A custom header value is invalid.
400	event_type_categories	An event notification rule has event types from multiple categories.
400	event_type_invalid	An event type is invalid.
400	event_type_overlap	An event notification rule has overlap in the event types.
400	event_types_empty	An event notification rule has overlap in the event types.
400	prefix_overlap	More than one event notification rule has overlap in the `objectNamePrefix` for the same event type.
400	signing_secret_invalid	The signing secret provided is not allowed.
400	rule_name_invalid	An event notification rule has an invalid rule name.
400	target_url_domain_invalid	There must not be a webhook URL that points to a Backblaze domain.
400	target_url_invalid	The target URL for an event notification rule is invalid.
400	target_url_protocol_invalid	The target URL for an event notification rule is not using https.
400	too_many_custom_headers	An event notification rule has more than 10 custom header name/value pairs.
400	too_many_event_notification_rules	There 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

status	code	description
401	bad_auth_token	The auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.
401	expired_auth_token	The auth token used has expired. Call b2_authorize_account again to get a new one.
401	unauthorized	The 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

status	code	description
403	transaction_cap_exceeded	Transaction cap exceeded. To increase your cap, sign in to your B2 Cloud Storage account online. Then select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar.

Was this article helpful?

What's Next

b2_start_large_file