{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Event Subscription API","description":"API documentation for Celonis APIs.","siteUrl":"https://developer.celonis.com/","keywords":"celonis developer portal, celonis apis, celonis api reference docs","lang":"en-US","llmstxt":{"hide":false,"description":"Celonis API documentation","sections":[{"title":"API Docs","description":"Available Celonis API Docs","includeFiles":["**/*.md"],"excludeFiles":[]},{"title":"API Specs","description":"All Celonis API specifications","includeFiles":["**/openapi.yaml"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"event-subscription-api","__idx":0},"children":["Event Subscription API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/process-intelligence-apis/subscription-api/notifications"},"children":["Email notifications for the Event Subscription API"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The steps that the Event Subscription API consumer follows to start receiving spontaneous events are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["discover the available triggers of a Knowledge Model (KM);"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["provision a subscription to the selected KM trigger (with an option to ignore callback errors and continue with the next event - configuration: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKIP_ERRORS"]},");",{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Event Subscription API allows you to subscribe to a maximum of 10,000 Celonis triggers."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Celonis emits spontaneous events to the consumer webhook when the trigger is fired."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This workflow is depicted in the following sequence diagram (click to enlarge):"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\nparticipant Callback Webhook \nparticipant API Consumer \nNote right of API Consumer: Celonis authentication/authorization \nrect rgb(128, 128, 128)\nAPI Consumer->>Subscriptions: List Subscriptions GET intelligence/api/subscriptions\nactivate Subscriptions \nSubscriptions-->>API Consumer: [Subscription List] \ndeactivate Subscriptions \nAPI Consumer->>Knowledge Models: List Triggers GET intelligence/api/knowledge-models/$km-id/triggers \nactivate Knowledge Models\nKnowledge Models-->>API Consumer: [Trigger List] \ndeactivate Knowledge Models\nend\nrect rgb(128, 128, 128)\nAPI Consumer->>Knowledge Models: Create Subscription to Trigger POST intelligence/api/knowledge-models/$km-id/triggers/$trigger-id/subscriptions \nactivate Knowledge Models\nKnowledge Models-->>API Consumer: {id:$subscription-id} \ndeactivate Knowledge Models\nend\nloop Event Emission\nNote right of Callback Webhook: Outbound authentication/authorization \nSubscriptions-->>Subscriptions: Trigger Fired\nSubscriptions-->>Callback Webhook: Event [{$trigger-id,$subscription-id,$event-id,$offset,{event structure}}]\nend\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\nparticipant Callback Webhook \nparticipant API Consumer \nNote right of API Consumer: Celonis authentication/authorization \nrect rgb(128, 128, 128)\nAPI Consumer->>Subscriptions: List Subscriptions GET intelligence/api/subscriptions\nactivate Subscriptions \nSubscriptions-->>API Consumer: [Subscription List] \ndeactivate Subscriptions \nAPI Consumer->>Knowledge Models: List Triggers GET intelligence/api/knowledge-models/$km-id/triggers \nactivate Knowledge Models\nKnowledge Models-->>API Consumer: [Trigger List] \ndeactivate Knowledge Models\nend\nrect rgb(128, 128, 128)\nAPI Consumer->>Knowledge Models: Create Subscription to Trigger POST intelligence/api/knowledge-models/$km-id/triggers/$trigger-id/subscriptions \nactivate Knowledge Models\nKnowledge Models-->>API Consumer: {id:$subscription-id} \ndeactivate Knowledge Models\nend\nloop Event Emission\nNote right of Callback Webhook: Outbound authentication/authorization \nSubscriptions-->>Subscriptions: Trigger Fired\nSubscriptions-->>Callback Webhook: Event [{$trigger-id,$subscription-id,$event-id,$offset,{event structure}}]\nend\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The subscription state transitions are depicted below (click to enlarge):"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"%%{init: { \"themeVariables\": { \"fontSize\": \"22px\" }, \"flowchart\": { \"useMaxWidth\": true } }}%%\nstateDiagram-v2\n[*]-->Active: Action (Create Subscription)\nActive-->Failed: HTTP callback error (transient errors)\nFailed-->Suspended: 8h in Failed status\nActive-->Rejected: HTTP callback error (rejection errors)\nActive-->Paused: Action(Pause Subscription)\nFailed-->Active: Action(Update Subscription) or Action(Replay Subscription) or HTTP success/Auto-recovery\nRejected-->Active: Action(Update Subscription) or Action(Replay Subscription)\nPaused-->Active: Action(Resume Subscription) or Action(Update Subscription) or Action(Replay Subscription)\nSuspended-->Active: Action(Update Subscription)\nActive-->[*]: Action(Delete Subscription)\nFailed-->[*]: Action(Delete Subscription)\nRejected-->[*]: Action(Delete Subscription)\nPaused-->[*]: Action(Delete Subscription)\nSuspended-->[*]: Action(Delete Subscription)\n","diagramHtml":"","diagramHtmlDark":""},"children":["%%{init: { \"themeVariables\": { \"fontSize\": \"22px\" }, \"flowchart\": { \"useMaxWidth\": true } }}%%\nstateDiagram-v2\n[*]-->Active: Action (Create Subscription)\nActive-->Failed: HTTP callback error (transient errors)\nFailed-->Suspended: 8h in Failed status\nActive-->Rejected: HTTP callback error (rejection errors)\nActive-->Paused: Action(Pause Subscription)\nFailed-->Active: Action(Update Subscription) or Action(Replay Subscription) or HTTP success/Auto-recovery\nRejected-->Active: Action(Update Subscription) or Action(Replay Subscription)\nPaused-->Active: Action(Resume Subscription) or Action(Update Subscription) or Action(Replay Subscription)\nSuspended-->Active: Action(Update Subscription)\nActive-->[*]: Action(Delete Subscription)\nFailed-->[*]: Action(Delete Subscription)\nRejected-->[*]: Action(Delete Subscription)\nPaused-->[*]: Action(Delete Subscription)\nSuspended-->[*]: Action(Delete Subscription)\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is how each subscription operation affects status transitions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create Subscription"]},": The subscription is created in status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]}," and an internal queue is provisioned to hold the produced events (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: [Start]-->Active"]},").",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It remains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]}," as long as the events are successfully emitted to the callback webhook."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upon successful event emission, the subscription ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["latestSucceedEvent"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["latestSucceedOffset"]}," are updated."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Failed"]}," (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: Active-->Failed"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the subscription configuration is set equal to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKIP_ERRORS"]},", then ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["failed"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["rejected"]}," events are ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["skipped and permanently lost"]},". Otherwise, the events remain in queue until callback webhook restoration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["auto-recovery"]}," process checks periodically the status of the callback webhook in case of a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["failed"]}," subscription and if it is restored, the events pending in queue are emitted and the subscription goes back to status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]}," (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: Failed-->Active"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the subscription remains in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Failed"]}," status for longer than a configurable period (8 hours), then the subscription goes to state ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Suspended"]},". The auto-recovery process ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["stops"]},", the event queue is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["destroyed"]}," and all events are lost (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: Failed-->Suspended"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upon rejected event emission, a configurable number of retries occurs and if it is still rejected , the subscription goes to state ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Rejected"]}," (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: Active-->Rejected"]},"). The error codes indicating event rejection are:"]}]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rejection Status Codes"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rejection Messages"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Bad Request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Unauthorized"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["402"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Payment Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Forbidden"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Not Found"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["405"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Method Not Allowed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["406"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Not Acceptable"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Gone"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["413"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Payload Too Large"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["414"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["URI Too Long"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["415"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Unsupported Media Type"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Unprocessable Content"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["431"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Request Header Fields Too Large (RFC 6585)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["451"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Unavailable For Legal Reasons (RFC 7725)"]}]}]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Subscription"]},": This is the way to recover a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Failed"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Suspended"]}," subscription or to change their callback details (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: Failed-->Active"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Suspended-->Active"]},")."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pause Subscription"]},": The API consumer may pause an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]}," subscription. Then it goes to state ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paused"]}," and stops emitting events. The events remain in queue (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: Active-->Paused"]},")."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resume Subscription"]},": The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paused"]}," subscription can be resumed, goes back to state ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]}," and starts either from the offset it was paused or it starts without history by emitting only fresh events (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: Paused-->Active"]},")."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replay Subscription"]},": Events from the subscription queue can be re-emitted from any state excluding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Suspended"]},", the subscription goes to state ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]}," and starts re-emission from the offset specified in the request (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["any state"]},"-->Active"]},")."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delete Subscription"]},": It can be requested at any status. The subscription and the downstream event queue are destroyed (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["State Transition: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["any state"]}," -->[End]"]},")."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each subscription has an owner (the creator) and its lifecycle can only be managed by the owner or an administrator."]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notifications","__idx":2},"children":["Notifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information on these notifications and the actions required, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/process-intelligence-apis/subscription-api/notifications"},"children":["Email notifications for the Event Subscription API"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-considerations","__idx":3},"children":["Further Considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In order to have access to a specific Knowledge Model and its triggers, the Knowledge Model must be published in the Celonis Platform."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The returned data corresponds to the last ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["published"]}," version of the Knowledge Model."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"feedback","__idx":4},"children":["Feedback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We value your feedback and are constantly striving to improve our APIs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.google.com/forms/d/e/1FAIpQLSeHANiDNRaHNCbdgH0hc1kQv35V2yHb5gkDpZTYjoT-6Gd-rQ/viewform?usp=sf_link"},"children":["form"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your input is important to us and will help us make our APIs even better."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Thank you for your time and support!"]}]},"headings":[{"value":"Event Subscription API","id":"event-subscription-api","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Notifications","id":"notifications","depth":2},{"value":"Further Considerations","id":"further-considerations","depth":2},{"value":"Feedback","id":"feedback","depth":2}],"frontmatter":{"seo":{"title":"Event Subscription API"}},"lastModified":"2026-04-14T22:25:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/process-intelligence-apis/subscription-api/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}