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
How it works
- 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.
- When an upload finishes and the key matches the filters, IBEE sends a
POSTrequest to your webhook. - Your webhook reads the request and does its work. Reply quickly with a
2xxstatus, 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
POSTrequests, for examplehttps://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
Open Event Notifications
Open the bucket, click Settings, then Event Notifications. Click Add Notification on the Webhook Notifications card.
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.
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.
Add a notification with the API
PUT replaces all of the bucket’s notifications with the list you send:
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:
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
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.
