Event Subscription API

This documentation describes how to interact with the Celonis Event Subscription REST API.

Goals

This API is used to discover business triggers, subscribe to them, manage event subscriptions and emit spontaneous events.

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 );
  • Celonis emits spontaneous events to the consumer webhook when the trigger is fired.

This workflow is depicted in the following sequence diagram:

Callback WebhookAPI ConsumerSubscriptionsKnowledge ModelsCelonisauthentication/authorizationCallback Webhookauthentication/authorizationencryption,HMAC signingloop[Event Emission]List SubscriptionsGET intelligence/api/subscriptions[Subscription List]List TriggersGET intelligence/api/knowledge-models/$km-id/triggers[Trigger List]Create Subscription to TriggerPOST intelligence/api/knowledge-models/$km-id/triggers/$trigger-id/subscriptions{id:$subscription-id}Trigger FiredEvent[{$trigger-id,$subscription-id,$event-id,$offset,{event structure}}]Callback WebhookAPI ConsumerSubscriptionsKnowledge Models

The subscription state transitions are depicted below:

Action(Create Subscription)
HTTP calback error
8h in Failed status
Action(Pause Subscription)
Action(Update Subscription) or Action(Replay Subscription) or HTTP success/Auto-recovery
Action(Resume Subscription) or Action(Update Subscription) or Action(Replay Subscription)
Action(Update Subscription)
Action(Delete Subscription)
Action(Delete Subscription)
Action(Delete Subscription)
Action(Delete Subscription)
Active
Failed
Suspended
Paused

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, 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 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 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 ).
  • 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.

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!