Managing an event subscription

In this tutorial we will guide you through the different subscription management endpoints.

List of Knowledge Models

As you saw in the Getting Started page, you can get the full list of Knowledge Models that you have access to, creating a request to https://<team>.<cluster>.celonis.cloud/intelligence/api/knowledge-models (remember that you need to replace <team> and <cluster> with your own values).

Knowledge Models response

List of Knowledge Model Triggers

You can get the full list of triggers that a Knowledge Model has, creating a request to https://<team>.<cluster>.celonis.cloud/intelligence/api/knowledge-models/<km_id>/triggers. For this URL, you will need to replace the <km_id> with the Knowledge Model id that you got from the previous endpoint.

Knowledge Models filters

Creating a new Subscription

To create a new subscription for an Celonis KM Trigger you need to consume the next endpoint.

Copy
Copied
POST
/knowledge-models/{{km-id}}/triggers/{{trigger-id}}/subscriptions

{
    "name": "new subscription with headers",
    "callbackInfo": {
        "uri": "https://my-awesome-webhook.com",
        "protocol":"HTTPS",
        "headers": {
            "Authorization" : "my bearer token"
        }
    }
}

km-id refers to the knowledge model that is existing at the Celonis Platform. trigger-id refers to the trigger that is existing at the Celonis Platform.

All the attributes (with the exception of the headers) of the payload are mandatory.

name must be shorter than 1024. callbackInfo.uri uri used for the API to forward events emitted from Celonis Platform. 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. 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.

Updating an existing Subscription

To update an existing subscription, you need to consume the next endpoint.

Copy
Copied
PUT
/subscriptions/{{subscription-id}}

{
    "name": "updated subscription with headers",
    "callbackInfo": {
        "uri": "https://my-awesome-webhook.com",
        "protocol":"HTTPS",
        "headers": {
            "Authorization" : "my bearer token"
        }
    }
}

subscription-id refers to the subscription to update. It must exist in the API.

All the attributes of the payload (with the exception of the headers) are mandatory.

  • name the subscription name, which must be must be shorter than 1024 characters.
  • callbackInfo.uri uri used for the API to forward events emitted from Celonis Platform.
  • 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.
  • 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.

In case of updating a Subscription which was failing, it will be set back to ACTIVE status.

Pausing a Subscription

To pause an active subscription, you need to consume the next endpoint.

Copy
Copied
PATCH
/subscriptions/{{subscription-id}}/pause

subscription-id refers to the subscription to pause. It must exist in the API.

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.

Resuming a Subscription

To resume a paused subscription, you need to consume the next endpoint.

Copy
Copied
PATCH
/subscriptions/{{subscription-id}}/resume

subscription-id refers to the subscription to resume. It must exist in the API.

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.

Unsubscribing

To remove an existing subscription you need to consume the next endpoint.

Copy
Copied
DELETE
/subscriptions/{{subscription-id}}

subscription-id refers to the subscription to unsubscribe. It must exist in the API.

Once this action is executed, the subscription will be no longer visible at Celonis Platform, and all its data is removed from the API.

Manual extraction (reconcile endpoint)

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.

To manually extract data, you need to consume the next endpoint.

Copy
Copied
PATCH
/subscriptions/{{subscription-id}}/events

subscription-id refers to the subscription to reconcile. It must exist in the API.

Once this action is executed, the next 50 events will be taken. Bear in mind this action will remove those events from the system.

Copy
Copied
{
    "pageSize": 2,
    "total": 0,
    "content": [
        {
            "subscriptionId": "XXX-YYY-ZZZZ",
            "triggerId": "97185b79-d6e9-4425-bbee-225627533149",
            "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}"
        },
        {
            "subscriptionId": "XXX-YYY-ZZZZ",
            "triggerId": "97185b79-d6e9-4425-bbee-225627533149",
            "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}"
        }
    ]
}

pageSize refers to the events returned in the page. total refers to the total events still at the API. content events as raw JSON.

Replay a subscription

To replay the subscription to receive events from a position, you need to consume the next endpoint.

Copy
Copied
PATCH
/subscriptions/{{subscription-id}}/replay?fromOffset=10

subscription-id refers to the subscription to replay. It must exist in the API.

Optionally, you can specify the offset from receiving past events. Just append the fromOffset url parameter with a value between 0 and the latest known position.

Untransferred data

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:

  • The subscription started to fail and is still within the time window to sort it out (after 8 hours the service is suspended).
  • The subscription is paused.

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.

Finally, the data is kept at the API for 7 days, after the period of time all the pending data will be discarded.