Notifications

Notifications, sometimes referred to as "Webhooks" in other systems, allow you to subscribe to specific events throughout the Buckets platform. This page will teach you how to create those subscriptions, if you are looking for more information on receiving and parsing notifications, see the Handling Notifications guide.

Available Events

Use Notifications to be alerted when actions are taken on a file or bucket. Currently the only supported Notification channel is a JSON webhook. Here are the available events:

EventDescription
bucket.createdFires when a new Bucket is created.
bucket.updatedFires when a Bucket is updated.
bucket.deletedFires when a Bucket is deleted.
user.createdFires when a new User is created.
user.updatedFires when a User is updated.
user.deletedFires when a User is deleted.
file.uploadedFires when a new file is uploaded inside of a bucket.
file.deletedFires when a file is deleted inside of a bucket.

The Notification Model

  • Name
    id
    Type
    string
    Description

    Unique identifier for the notification.

  • Name
    bucket_id
    Type
    string
    Description

    The id of the Bucket this notification is attached to.

  • Name
    events
    Type
    array
    Description

    A list of event types that this Notification is subscribed to.

  • Name
    active
    Type
    boolean
    Description

    Whether or not the Notification is currently active. If set to false, all notification attempts will be paused.

  • Name
    webhook_url
    Type
    string
    Description

    The URL that we will send the notification payload.

  • Name
    include_file_contents
    Type
    boolean
    Description

    This property is only used if the event is file.uploaded or file.deleted. If set to true, the entire contents of the file will be provided inside of the webhook payload.

  • Name
    paths
    Type
    array
    Description

    An optional list of directory paths. If specified, the file.uploaded and file.deleted notifications will only fire if an action was taken inside of one of these directories. An empty array or excluded property means that the notification will fire on all actions in this Bucket. You can use wildcard paths as well, like /dir1/*/dir2.

  • Name
    created_at
    Type
    timestamp
    Description

    Unix Timestamp of when the user was created.

POST/v1/notifications

Create a Notification

Use this route to create a new Notification for a specific Bucket.

Request

{
  "bucket_id": "bio_test_buc_1amaj5125as",
  "events": [
      "file.uploaded"
  ],
  "webhook_url": "https://example.com",
  "include_file_contents": true
}

Response

{
  "id": "bio_test_not_1amaj5125as",
  "bucket_id": "bio_test_buc_1amaj5125as",
  "events": [
      "file.uploaded"
  ],
  "webhook_url": "https://example.com",
  "include_file_contents": true,
  "active": true,
  "created_at": 692233200
}