Object Notifications | Tigris Object Storage Documentation

On this page

Tigris object notifications allow you to receive notifications via a webhook. These events allow you to keep track of when objects are created, updated, or deleted for a specific bucket.

Enable Object Notifications via Tigris Dashboard

To enable object notifications, you need to set up a webhook in the Tigris Dashboard. This can be done in Settings for the bucket.

Here's a short video demonstration on enabling object notifications:

Webhook

Object notifications are delivered via a webhook, and obey the following rules:

• Tigris will make an HTTP POST request to the webhook URL with the event payload.
• A 2xx status code acknowledges the request was successful. Any other status is treated as a failure and retried.
• If a webhook request takes longer than 10 seconds the request will be aborted and retried.

Webhook Authentication

Tigris supports basic authentication and token authentication for webhooks. When configuring the webhook in the Tigris Dashboard, you can choose the authentication type and provide the necessary credentials.

For basic authentication, the header will set as follows:

Authorization: Basic <base64 encoded username:password>

For token authentication, the header will set as follows:

Authorization: Bearer <token>

Notification Types

Tigris supports the following notification types:

• OBJECT_CREATED_PUT: An object was created via a PUT request.
• OBJECT_CREATED_MULTIPART: An object was created via a multipart upload.
• OBJECT_CREATED_COPY: An object was created by copying an existing object.
• OBJECT_DELETED: An object was deleted.
• OBJECT_TRANSITIONED: An object was transitioned to a different storage class (for example, via a lifecycle rule).
• OBJECT_RENAME: An object was renamed.

Notification Format

Each notification will be a JSON object with the following fields:

An example notification payload is:

{

"events": [
    {
      "eventVersion": "1",
      "eventSource": "tigris",
      "eventName": "OBJECT_CREATED_PUT",
      "eventTime": "2023-05-15T10:30:00.000Z",
      "bucket": "my-bucket",
      "object": {
        "key": "path/to/myfile.txt",
        "size": 1024,
        "eTag": "d41d8cd98f00b204e9800998ecf8427e"
      }
    },
    {
      "eventVersion": "1",
      "eventSource": "tigris",
      "eventName": "OBJECT_DELETED",
      "eventTime": "2023-05-15T11:45:00.000Z",
      "bucket": "my-bucket",
      "object": {
        "key": "path/to/anotherfile.jpg",
        "size": 2048,
        "eTag": "c4ca4238a0b923820dcc509a6f75849b"
      }
    }
  ]
}

Filtering

Object notifications support adding a SQL-like query to filter the events that are sent to the webhook. The query is configured in the Tigris Dashboard. The filtering uses the SQL-like syntax defined in Metadata Querying. It also supports the extra Event-Type field to filter by event type.

An example to only receive notifications for a key with a prefix of images/:

WHERE `key` REGEXP "^images"

Or to only receive notifications for delete events:

WHERE `Event-Type` = "OBJECT_DELETED"

Pricing

See Pricing for how object notifications are charged.

Notification ordering guarantees and delivery

Tigris Object Notifications are designed to be delivered at least once. This means that in rare cases, you might receive duplicate notifications for the same event. Aim to design your application to handle potential duplicates.

Due to Tigris being a globally distributed object store, notifications can be sent out of order. This is due to objects being modified in multiple regions. A single region then collates those events and sends them to the webhook. The Last-Modified timestamp can be used to determine the order of the events.

Next steps

• Check out the Example Webhook for more details on how to use them in your application.