Set Bucket Webhooks

Replace the webhook notification rules of a bucket you own.

Endpoint	Method	Admin Required
`/api/v1/buckets/:bucketName/notifications`	PUT	No

Replaces the webhook notification rules for a bucket you own, overwriting the existing configuration entirely. Send an empty rules array to remove all webhooks. See Webhooks for payload format, signing, and retry behavior.

Path Parameters

bucketName

string required

The name of the bucket.

Request Body

rules

array required

Up to 16 rules. Each rule has the fields below.

Rule fields

string required

The rule's UUID. Send the all-zero UUID (00000000-0000-0000-0000-000000000000) for a new rule - the server assigns a real id and returns it.

url

string required

The http or https endpoint to deliver events to. URLs resolving to private, loopback, or link-local addresses can only be set by administrators.

secret

string

Optional signing secret. When set, each delivery carries an X-Alarik-Signature-256 HMAC-SHA256 header the receiver can verify.

events

array required

One or more event types to subscribe to (see below). At least one is required.

prefix

string

Optional key prefix filter - only objects whose key starts with this value trigger the rule.

suffix

string

Optional key suffix filter - only objects whose key ends with this value trigger the rule.

enabled

boolean required

Whether the rule is active. Disabled rules are stored but never deliver.

Supported event types

Event	Fires when
`s3:ObjectCreated:*`	Any object creation
`s3:ObjectCreated:Put`	A `PutObject`
`s3:ObjectCreated:Copy`	A `CopyObject`
`s3:ObjectCreated:CompleteMultipartUpload`	A multipart upload completes
`s3:ObjectRemoved:*`	Any object removal
`s3:ObjectRemoved:Delete`	A permanent delete
`s3:ObjectRemoved:DeleteMarkerCreated`	A delete marker is created (versioned bucket)
`s3:LifecycleExpiration:*`	Any lifecycle expiration
`s3:LifecycleExpiration:Delete`	A lifecycle rule permanently deletes an object
`s3:LifecycleExpiration:DeleteMarkerCreated`	A lifecycle rule creates a delete marker

Example

{
    "rules": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "url": "https://example.com/webhook",
            "secret": "a-shared-signing-secret",
            "events": ["s3:ObjectCreated:*"],
            "prefix": "uploads/",
            "suffix": ".jpg",
            "enabled": true
        }
    ]
}

Response

Returns the saved rules, each with its server-assigned id:

{
    "rules": [
        {
            "id": "6ff08747-4ec0-48fd-a0b1-f5adda6d3161",
            "url": "https://example.com/webhook",
            "events": ["s3:ObjectCreated:*"],
            "prefix": "uploads/",
            "suffix": ".jpg",
            "enabled": true
        }
    ]
}

Errors

Status	Reason
`400`	Missing bucket name, invalid URL, unknown event type, no events, or more than 16 rules
`403`	A non-admin tried to set a private/loopback URL
`404`	Bucket not found (or not owned by you)

Get Bucket Webhooks

Retrieve the webhook notification rules of a bucket you own.

Test Bucket Webhook

Send a test event to one of a bucket's webhook rules.