Handling Notifications

In this guide, we will look at how to consume notifications from the Buckets API. If you are looking for the Notification resource (including the list of events and how to create a Notification), see the Notifications Resource.

Consuming Notifications

When your app receives a notification request from Buckets, check the event attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a bucket, user, etc.

Example notification payload

{
  "event": "file.uploaded",
  "fired_at": 692233200,
  "bucket_id": "bio_test_buc_1amaj5125as", // Only provided for bucket.* events
  "user_id": "bio_test_usr_1amaj5125as", // Only provided for user.* and file.* events
  "file_path": "/dir1/file_name.csv", // Only provided for file.* events
  "file_name": "file_name.csv", // Only provided for file.* events
  "file_contents": "..."
}

In the example above, a file was uploaded, and the payload type is a file.

See all event types

Your server must return an HTTP 2xx status code for the Notification to be acknowledged. If the response times out or returns a non-2xx status code, we will attempt to deliver the notification using exponential backoff over the next 24 hours.

Security

To know for sure that a notification was, in fact, sent by Buckets instead of a malicious actor, you can verify the request signature. Each notification request contains a header named x-buckets-signature, and you can verify this signature by using your secret notification key. The signature is an HMAC hash of the request payload hashed using your notification secret key. Here is an example of how to verify the signature in your app:

Verifying a request

const signature = req.headers['x-buckets-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-buckets-signature header, you can be sure that the request was truly coming from Buckets. It's essential to keep your secret notifications key safe — otherwise, you can no longer be sure that a given notification was sent by Buckets. Don't commit your secret notification key to GitHub!