Event Notifications Reference Guide

This article provides information about Backblaze B2 Cloud Storage Event Notifications such as rule structure, event types, and webhooks.

To create and use Event Notifications, click here.

You can also use the Backblaze B2 API to manage Event Notifications:

• Get Bucket Notification Rules
• Set Bucket Notification Rules

Event Notification Rules

Event Notifications instruct Backblaze B2 to perform actions when certain events happen in the system. You can set up rules to trigger a webhook. An HTTP POST request is sent to a URL that you configure whenever certain events occur, such as an object upload or an object being created in a destination bucket during replication.

A bucket can have up to 25 Event Notifications. Event Notification rules are not supported for object download events or for replication of objects from a source bucket. All webhook invocations use the POST HTTP method and must use HTTPS protocol. You must allow incoming requests to your webhook endpoint from the IP address blocks that are listed in the Backblaze IP Address List.

Event Notification Rule Structure

Each Event Notification rule can have the following parameters.

Event Types

Backblaze B2 currently supports the following event types for Event Notifications. New event types may be added in the future, so ensure that your code can handle the potential addition of new event types.

Event types support the wildcard * only in the final component. For example, b2:ObjectCreated:* corresponds to the following event types:

• b2:ObjectCreated:Upload
• b2:ObjectCreated:MultipartUpload
• b2:ObjectCreated:Copy
• b2:ObjectCreated:Replica
• b2:ObjectCreated:MultipartReplica


The wildcard also matches any new event types within the same category that you may add in the future.

An Event Notification rule must not specify any event types that overlap. For example, if both b2:ObjectCreated:Upload and b2:ObjectCreated:* are event types in the same Event Notification rule, it constitutes an error.

The following example shows a request structure for an Event Notification rule using b2_set_bucket_notification_rules:

{
  "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"
      },
    }
  ]
}

The following example shows a response structure from an Event Notification rule:

{
  "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"
      },
    }
  ]
}

Event Type Categories

An event type category is the event type without the final component. For example, the category for the event type b2:ObjectCreated:Copy is b2:ObjectCreated. The three event type categories are:

• b2:ObjectCreated
• b2:ObjectDeleted
• b2:HideMarkerCreated

It is possible to use event types from different categories in the same Event Notification rule. For example, you could use both the event types b2:ObjectCreated:Copy and b2:HideMarkerCreated:Hide in the same rule. Additionally, you can make a rule that uses event types from the same category. For example, you could use both event types b2:ObjectCreated:Copy and b2:ObjectCreated:Replica in the same rule.

Webhooks

Event Notifications are designed with an at-least-once delivery guarantee to ensure reliable delivery, even in the presence of network or system failures.

When an event that matches an Event Notification rule occurs within a bucket, Backblaze B2 sends a webhook (an HTTP POST request with a JSON-encoded payload) to the endpoint URL that you specify in the rule.

Backblaze B2 sets a three-second timeout on the webhook request. Your code should defer any substantial processing until after sending a 200 response to reply within the time limit. Backblaze B2 will retry the request if your endpoint does not return a 200 response within the time limit.

If the rule has an hmacSha256SigningSecret, each webhook invocation includes an X-Bz-Event-Notification-Signature HTTP header. The value of this header is the lowercase hex-encoded HMAC SHA-256 signature of the request payload, signed using the hmacSha256SigningSecret from the Event Notification rule. You can use the header and value to ensure that the webhook invocation is coming from Backblaze. The signature value is prepended by the version number. 

Here is an example of a signature value: v1=2c86b8e1f15f41f805f3331f3cf4eb20875be8887ab734b2cdccfa2350e5e231.

Additionally, any custom HTTP headers that were defined in the Event Notification rules are included in the webhook requests.

The following example shows a webhook HTTP request (with long strings shortened for readability):

POST /sampleurl HTTP/1.1
Host: www.example.com
Content-Length: 468
X-Bz-Event-Notification-Signature: v1=2c86b8e1f15f41f8...
X-My-Custom-Header-1: myCustomHeaderVal1
X-My-Custom-Header-2: myCustomHeaderVal2
User-Agent: B2/EventNotifications
Content-Type: application/json; charset=UTF-8

{
  "events": [ 
    {
      "accountId": "e85c6a500333",
      "bucketId": "aea8c5bc362ae55070130333",
      "bucketName": "mySampleBucket",
      "eventId": "ba9a8e4eacda8b4b7d23a0ec1f04046342c319f3c608903e794c45a5b57184be",
      "eventTimestamp": 1684793309123,
      "eventType": "b2:ObjectCreated:Upload",
      "eventVersion": 1,
      "matchedRuleName": "mySampleRule1",
      "objectName": "objectName.txt",
      "objectSize": 10495842,
      "objectVersionId": "4_zaea8c5bc362a..."
    }
  ]
}

The following metadata fields are in the JSON payload.

Verifying the Webhook Request Signature

If you provide an hmacSha256SigningSecret, then the webhook request includes an X-Bz-Event-Notification-Signature HTTP header that contains the HMAC SHA-256 signature of the request payload. The signature header value comprises the signature version, always v1, followed by an equals sign =, followed by the lowercase hex-encoded signature value. You must provide an hmacSha256SigningSecret to get a signature.

Here is an example of the HTTP header, with the signature value truncated for readability. The actual signature value contains 64 lowercase hex characters, encoding the 256-bit message digest.

X-Bz-Event-Notification-Signature: v1=2c86b8e1f15f41f8...

To verify the signature, create an HMAC SHA-256 digest using the hmacSha256SigningSecret from the Event Notification rule as the key, with the request payload as the data. The resulting hex-encoded HMAC digest value must match the signature in the header. If it matches, your code may perform additional message validation—such as parsing the Event Notification from the JSON-encoded request body—before responding to the request with a 200 OK HTTP response. Your code may then continue to process the Event Notification according to your needs. If the calculated digest value does not match the request signature, you should respond to the request with a 401 Unauthorized HTTP response and cease processing the request.

The following code is an example of how you might verify the webhook request signature in JavaScript. If you intend to check the signature, you should first make sure that you have set the hmacSha256SigningSecret in the Event Notification rule. Otherwise, the signature will be missing and the code will exit prematurely.

import { createHmac } from 'node:crypto';

// Is the signature header present?
const signature = req.headers['x-bz-event-notification-signature'];
if (!signature) {
  res.status(401).send('Missing signature header');
  return;
}

// Does the signature have the correct form?
const pair = signature.split('=');
if (!pair || pair.length !== 2) {
  res.status(401).send('Invalid signature format');
  return;
}

// Is the signature version correct?
const version = pair[0];
if (version !== 'v1') {
  res.status(401).send('Invalid signature version');
  return;
}

// Note - at present (4/15/24), test events need special handling
// * Test event requests are signed with a dummy key
if (event.body.eventType === 'b2:TestEvent') {
  // Don't bother validating signature on test events, since we know it will not match
  console.log('Skipping signature verification for test event')
} else {
  const receivedSig = pair[1];
  // req.body must contain the raw, unparsed body
  const calculatedSig = createHmac('sha256', signingSecret)
    .update(req.body)
    .digest('hex');
  if (receivedSig !== calculatedSig) {
    res.status(401).send('Invalid signature');
    return;
  }
}

// Parse the event notification payload from the request body
let payload
try {
  payload = JSON.parse(req.body);
} catch (e) {
  res.status(400).send('Bad request');
  return;
}

// Respond with success before any further processing, 
// since B2 needs the response within three seconds.
res.status(200).send('OK');

// Continue processing

Application Key Capabilities

New application key capabilities have been added to support the Event Notifications feature:

For more information, see Application Keys and Application Key Capabilities.