Events and Webhooks

To receive real-time notifications about events in the Swift API, you can subscribe to object lifecycle events with the Create Event Subscription API. Once a URL is registered for a subscription, Swift will send HTTP POST requests to that URL when the specified events occur.

Despite webhook support, the recommended way to listen for events is to poll over the List Events API using pagination. Webhooks make it difficult to receive events in local environments without a network tunnelling tool like Ngrok.

Event notifications have an event_category field that indicates the type of event. These categories are purposefully simple, only indicating if an object is created or updated. This requires fetching the updated object from the object’s API endpoint to curb issues that may arise from concurrent object notifications.

​

Webhook Delivery

Webhook delivery is considered successful on a 2xx or 4xx response. 5xx responses are retried with exponential backoff up to 8 times.

Your webhook handler should return a successful response as soon as possible, ideally immediately passing the event to an event queue or concurrent worker.