Event Subscription API

The Event Subscription API is used to discover business triggers, subscribe to them, manage event subscriptions and emit spontaneous events. Each of these actions will generate and send email notifications containing alerts, updates, status changes, and other types of information related to your subscriptions. It is recommended that you review these email notifications to check for any required actions on your part. For more information about the different types of notifications you may receive, refer to Email notifications for the Event Subscription API.

How it works

The steps that the Event Subscription API consumer follows to start receiving spontaneous events are:

• discover the available triggers of a Knowledge Model (KM);
• provision a subscription to the selected KM trigger (with an option to ignore callback errors and continue with the next event - configuration: SKIP_ERRORS );
  
  NOTE: The Event Subscription API allows you to subscribe to a maximum of 10,000 Celonis triggers.
  
  
• Celonis emits spontaneous events to the consumer webhook when the trigger is fired.

This workflow is depicted in the following sequence diagram:

The subscription state transitions are depicted below:

This is how each subscription operation affects status transitions:

• Create Subscription : The subscription is created in status Active and an internal queue is provisioned to hold the produced events ( State Transition: [Start]-->Active ).
  • It remains Active as long as the events are successfully emitted to the callback webhook.
  • Upon successful event emission, the subscription offset , latestSucceedEvent and latestSucceedOffset are updated.
  • Upon failed event emission due to a transient error, a configurable number of retries occurs and if it still fails, the subscription goes to state Failed ( State Transition: Active-->Failed ).
  • If the subscription configuration is set equal to SKIP_ERRORS , then failed or rejected events are skipped and permanently lost . Otherwise, the events remain in queue until callback webhook restoration.
  • The auto-recovery process checks periodically the status of the callback webhook in case of a failed subscription and if it is restored, the events pending in queue are emitted and the subscription goes back to status Active ( State Transition: Failed-->Active ).
  • If the subscription remains in Failed status for longer than a configurable period (8 hours), then the subscription goes to state Suspended . The auto-recovery process stops , the event queue is destroyed and all events are lost ( State Transition: Failed-->Suspended ).
  • Upon rejected event emission, a configurable number of retries occurs and if it is still rejected , the subscription goes to state Rejected ( State Transition: Active-->Rejected ). The error codes indicating event rejection are:

• Update Subscription : This is the way to recover a Failed or Suspended subscription or to change their callback details ( State Transition: Failed-->Active or Suspended-->Active ).
• Pause Subscription : The API consumer may pause an Active subscription. Then it goes to state Paused and stops emitting events. The events remain in queue ( State Transition: Active-->Paused ).
• Resume Subscription : The Paused subscription can be resumed, goes back to state Active and starts either from the offset it was paused or it starts without history by emitting only fresh events ( State Transition: Paused-->Active ).
• Replay Subscription : Events from the subscription queue can be re-emitted from any state excluding Suspended , the subscription goes to state Active and starts re-emission from the offset specified in the request ( State Transition: any state-->Active ).
• Delete Subscription : It can be requested at any status. The subscription and the downstream event queue are destroyed ( State Transition: any state -->[End] ).

Note: Each subscription has an owner (the creator) and its lifecycle can be managed only by the owner or an administrator.

Notifications

Once the Event Subscription API is active, users will also begin receiving email notifications regarding their subscriptions and triggers. Some of these notifications are for informative purposes only, such as confirming that a subscription was created or when a subscription has been paused. However, some of these notifications will require action from the user, such as when a subscription has failed or when the user reaches the maximum number of subscriptions allowed.

For more information on these notifications and the actions required, see Email notifications for the Event Subscription API.

Further Considerations

• In order to have access to a specific Knowledge Model and its triggers, the Knowledge Model must be published in the Celonis Platform.
• The returned data corresponds to the last published version of the Knowledge Model.

Feedback

We value your feedback and are constantly striving to improve our APIs.

If you have encountered any problems or have any suggestions for new features, please take a moment to share your thoughts with us through this form.

Your input is important to us and will help us make our APIs even better.

Thank you for your time and support!