Skip to navigation

Event Notifications

An event notification is a message IBEE sends to your app when something happens in a bucket — today, when a file is uploaded. The message is an HTTP POST request to a webhook: a web address on your server that you set up to receive it. Use it to start work automatically, such as making a thumbnail when an image arrives or importing a CSV file when it lands in imports/.

When to use event notifications

You want to…Use
React within moments to each upload (resize, scan, import)Event notification to your webhook
Process files on a schedule, in batchesA scheduled job that lists new keys with ListObjectsV2
Delete files after some timeA lifecycle rule
Know when a file is deletedNot available yet — deletion events aren’t delivered

How it works

  1. You add a notification on the bucket with your Webhook URL, the event type Creation of a new object, and optional Prefix and Suffix filters.
  2. When an upload finishes and the key matches the filters, IBEE sends a POST request to your webhook.
  3. Your webhook reads the request and does its work. Reply quickly with a 2xx status, and do long jobs in the background.

Before you begin

  • A bucket. See Create a bucket.
  • A webhook that is reachable from the internet over HTTPS and accepts POST requests, for example https://hooks.example.com/ibee.
  • Write access to the bucket’s settings, or a platform API token with object-storage.write.

Add a notification in the portal

1

Open Event Notifications

Open the bucket, click Settings, then Event Notifications. Click Add Notification on the Webhook Notifications card.

2

Enter the webhook URL

In Webhook URL, enter your endpoint, such as https://hooks.example.com/ibee. It receives a POST request for each matching event.

3

Choose the event type

Under Event Types, tick Creation of a new object.

Deletion of an object is shown, but deletion events aren’t delivered yet, and a notification with only that box ticked fails to save. Tick Creation of a new object.

4

Add filters (optional)

Expand Advanced Options:

FilterExampleEffect
Prefixuploads/Only keys that start with this
Suffix.jpgOnly keys that end with this

Leave both empty to be told about every upload in the bucket. Both are case-sensitive.

5

Save

Click Save Notification. The webhook appears in the Webhook Notifications list with its events, shown as Object Created.

Add a notification with the API

PUT replaces all of the bucket’s notifications with the list you send:

curl -X PUT "https://api.ibee.ai/v1/object-storage/buckets/my-bucket/notifications?workspace_id=YOUR-WORKSPACE-ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"configs": [{"events": ["upload"], "filter": {"prefix": "uploads/", "suffix": ".jpg"}, "webhook_url": "https://hooks.example.com/ibee"}]}'

events takes upload and delete (delete isn’t delivered yet). GET on the same path returns the notifications; DELETE removes all of them and needs object-storage.delete. The S3 call PutBucketNotificationConfiguration returns 501 on the S3 endpoint.

Verify

Upload a file that matches the filters, for example:

aws s3 cp cat.jpg s3://my-bucket/uploads/cat.jpg \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee

Then check your webhook’s logs for a POST request that arrived after the upload, and look for the key uploads/cat.jpg in its body. To test before your app is ready, point the webhook at a request-inspection service you trust and look at the request it receives.

Edit or delete a notification

Each webhook in the list has Edit and Delete. Edit opens the Edit Notification dialog; click Save Notification. Delete asks Delete this notification?; click Delete.

Limits

Value
Events deliveredUploads (object created)
Deletion eventsNot delivered yet
FiltersOne prefix and one suffix per notification, case-sensitive
WebhookMust be reachable from the internet; HTTPS recommended
S3 notification calls501; use the portal or REST API

Security tips

  • Use HTTPS for the webhook so event details aren’t sent in clear text.
  • Treat each request as a hint, not proof. Before acting on it, read the object with your S3 credential to confirm it exists.
  • Make your handler safe to run twice for the same key, in case a request is repeated.

Troubleshooting

You seeWhat it meansWhat to do
Please enter a webhook URL or Please enter a valid webhook URLThe URL is empty or not a full addressEnter a full URL such as https://hooks.example.com/ibee.
Please select at least one event typeNo event is tickedTick Creation of a new object.
Saving fails with only Deletion of an object tickedDeletion events aren’t supported yetTick Creation of a new object.
No requests arriveThe webhook isn’t reachable from the internet, a firewall blocks it, or the key doesn’t match the filtersTest the URL from outside your network; check the prefix and suffix (case-sensitive).
Too many requestsThe notification covers the whole bucketAdd a Prefix or Suffix.
Nothing for deleted filesDeletion events aren’t delivered yetTrack deletes in your app.