{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Managing an event subscription","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":"managing-an-event-subscription","__idx":0},"children":["Managing an event subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this tutorial we will guide you through the different subscription management endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-of-knowledge-models","__idx":1},"children":["List of Knowledge Models"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As you saw in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/process-intelligence-apis/subscription-api/get-started/getting-started"},"children":["Getting Started page"]},", you can get the full list of Knowledge Models that you"," ","have access to, creating a request to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://<team>.<cluster>.celonis.cloud/intelligence/api/knowledge-models"]}," (remember"," ","that you need to replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<team>"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<cluster>"]}," with your own values)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/knowledge-models.1689be958259b96c9cfa13712cf6bd227d18eab5f371ff290ea005a53a6c66c2.527729fc.png","alt":"Knowledge Models response"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-of-knowledge-model-triggers","__idx":2},"children":["List of Knowledge Model Triggers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can get the full list of triggers that a Knowledge Model has, creating a request to"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://<team>.<cluster>.celonis.cloud/intelligence/api/knowledge-models/<km_id>/triggers"]},". For this URL, you will need to"," ","replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<km_id>"]}," with the Knowledge Model id that you got from the previous endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/filters.85c06faa5a32f6bfdef7e2929fdfa7270cdf80395766fbfe608035f07cd63a6d.527729fc.png","alt":"Knowledge Models filters"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-a-new-subscription","__idx":3},"children":["Creating a new Subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a new subscription for an Celonis KM Trigger you need to consume the next endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST\n/knowledge-models/{{km-id}}/triggers/{{trigger-id}}/subscriptions\n\n{\n    \"name\": \"new subscription with headers\",\n    \"callbackInfo\": {\n        \"uri\": \"https://my-awesome-webhook.com\",\n        \"protocol\":\"HTTPS\",\n        \"headers\": {\n            \"Authorization\" : \"my bearer token\"\n        }\n    }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["km-id"]}," refers to the knowledge model that is existing at the Celonis Platform."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trigger-id"]}," refers to the trigger that is existing at the Celonis Platform."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All the attributes (with the exception of the headers) of the payload are mandatory."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," must be shorter than 1024."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackInfo.uri"]}," uri used for the API to forward events emitted from Celonis Platform."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackInfo.protocol"]}," the protocol used to forward events emitted from the Celonis Platform. It must fit with the callbackInfo.uri attribute. Otherwise it will fail into a Bad Request."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackInfo.headers"]}," map of key/value regarding all the headers that will be attached from the API when the event is forwarded to the consumer."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"updating-an-existing-subscription","__idx":4},"children":["Updating an existing Subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To update an existing subscription, you need to consume the next endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PUT\n/subscriptions/{{subscription-id}}\n\n{\n    \"name\": \"updated subscription with headers\",\n    \"callbackInfo\": {\n        \"uri\": \"https://my-awesome-webhook.com\",\n        \"protocol\":\"HTTPS\",\n        \"headers\": {\n            \"Authorization\" : \"my bearer token\"\n        }\n    }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription-id"]}," refers to the subscription to update. It must exist in the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All the attributes of the payload (with the exception of the headers) are mandatory."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," the subscription name, which must be must be shorter than 1024 characters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackInfo.uri"]}," uri used for the API to forward events emitted from Celonis Platform."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackInfo.protocol"]}," the protocol used to forward events emitted from the Celonis Platform. It must fit with the callbackInfo.uri attribute. Otherwise it will fail into a Bad Request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callbackInfo.headers"]}," map of key/value regarding all the headers that will be attached from the API when the event is forwarded to the consumer."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In case of updating a Subscription which was failing, it will be set back to ACTIVE status."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pausing-a-subscription","__idx":5},"children":["Pausing a Subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To pause an active subscription, you need to consume the next endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PATCH\n/subscriptions/{{subscription-id}}/pause\n\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription-id"]}," refers to the subscription to pause. It must exist in the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the subscription is paused, it will not stop forwarding events generated by Celonis Platform. Those events aren't lost and will be sent to the consumer once the subscription is resumed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resuming-a-subscription","__idx":6},"children":["Resuming a Subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To resume a paused subscription, you need to consume the next endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PATCH\n/subscriptions/{{subscription-id}}/resume\n\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription-id"]}," refers to the subscription to resume. It must exist in the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the subscription is resumed, it will forward new events generated by Celonis Platform, as well as the events that were pending when the subscription was paused."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"unsubscribing","__idx":7},"children":["Unsubscribing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To remove an existing subscription you need to consume the next endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"DELETE\n/subscriptions/{{subscription-id}}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription-id"]}," refers to the subscription to unsubscribe. It must exist in the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once this action is executed, the subscription will be no longer visible at Celonis Platform, and all its data is removed from the API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"manual-extraction-reconcile-endpoint","__idx":8},"children":["Manual extraction (reconcile endpoint)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the subscription is failing, in the meanwhile the subscription is fixed, is possible to manually extract the data from Celonis Platform in short batches."," ","This is what is called the Reconciliation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To manually extract data, you need to consume the next endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PATCH\n/subscriptions/{{subscription-id}}/events\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription-id"]}," refers to the subscription to reconcile. It must exist in the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once this action is executed, the next 50 events will be taken. Bear in mind this action will remove those events from the system."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"pageSize\": 2,\n    \"total\": 0,\n    \"content\": [\n        {\n            \"subscriptionId\": \"XXX-YYY-ZZZZ\",\n            \"triggerId\": \"97185b79-d6e9-4425-bbee-225627533149\",\n            \"signal\": \"{\\\"id\\\":\\\"a8ffef1d-aba0-4520-ae1a-02cecc7b7e4e\\\",\\\"recordIdentifier\\\":\\\"800A3000531000\\\",\\\"typedRecordIdentifier\\\":\\\"800A3000531000\\\",\\\"attributes\\\":[{\\\"attributeId\\\":\\\"ATTRIBUTE_1\\\",\\\"signalId\\\":\\\"a8ffef1d-aba0-4520-ae1a-02cecc7b7e4e\\\",\\\"value\\\":null,\\\"columnType\\\":\\\"STRING\\\"}],\\\"creationDate\\\":1699010395821}\"\n        },\n        {\n            \"subscriptionId\": \"XXX-YYY-ZZZZ\",\n            \"triggerId\": \"97185b79-d6e9-4425-bbee-225627533149\",\n            \"signal\": \"{\\\"id\\\":\\\"8cf03551-471c-41f0-a85c-e88646eef354\\\",\\\"recordIdentifier\\\":\\\"80000000130071000\\\",\\\"typedRecordIdentifier\\\":\\\"80000000130071000\\\",\\\"attributes\\\":[{\\\"attributeId\\\":\\\"ATTRIBUTE_1\\\",\\\"signalId\\\":\\\"8cf03551-471c-41f0-a85c-e88646eef354\\\",\\\"value\\\":\\\"D1\\\",\\\"columnType\\\":\\\"STRING\\\"}],\\\"creationDate\\\":1699010395821}\"\n        }\n    ]\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]}," refers to the events returned in the page."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," refers to the total events still at the API."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}," events as raw JSON."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"replay-a-subscription","__idx":9},"children":["Replay a subscription"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To replay the subscription to receive events from a position, you need to consume the next endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PATCH\n/subscriptions/{{subscription-id}}/replay?fromOffset=10\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription-id"]}," refers to the subscription to replay. It must exist in the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Optionally, you can specify the offset from receiving past events. Just append the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fromOffset"]}," url parameter with a value between 0 and the latest known position."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"untransferred-data","__idx":10},"children":["Untransferred data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Untransferred data means the data unable to forward to the consumer but saved at the API to retry later. The data can be saved at the API under two circunstances:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The subscription started to fail and is still within the time window to sort it out (after 8 hours the service is suspended)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The subscription is paused."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Untransferred data can be manually extracted using the reconcile endpoint."," ","But for active subscriptions with data remaining in the API, every 10 minutes our API will retry to forward the data to the consumer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Finally, the data is kept at the API for 7 days, after the period of time all the pending data will be discarded."]}]},"headings":[{"value":"Managing an event subscription","id":"managing-an-event-subscription","depth":1},{"value":"List of Knowledge Models","id":"list-of-knowledge-models","depth":2},{"value":"List of Knowledge Model Triggers","id":"list-of-knowledge-model-triggers","depth":2},{"value":"Creating a new Subscription","id":"creating-a-new-subscription","depth":2},{"value":"Updating an existing Subscription","id":"updating-an-existing-subscription","depth":2},{"value":"Pausing a Subscription","id":"pausing-a-subscription","depth":2},{"value":"Resuming a Subscription","id":"resuming-a-subscription","depth":2},{"value":"Unsubscribing","id":"unsubscribing","depth":2},{"value":"Manual extraction (reconcile endpoint)","id":"manual-extraction-reconcile-endpoint","depth":2},{"value":"Replay a subscription","id":"replay-a-subscription","depth":2},{"value":"Untransferred data","id":"untransferred-data","depth":2}],"frontmatter":{"seo":{"title":"Managing an event subscription"}},"lastModified":"2026-02-26T22:05:33.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/process-intelligence-apis/subscription-api/tutorials/learning/managing-subscription","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}