b2_set_bucket_notification_rules
    • Dark
      Light

    b2_set_bucket_notification_rules

    • Dark
      Light

    Article summary

    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
    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
    objectRequired

    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, "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
    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
    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. 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?