**BETA API**
Subscriptions are queries into real-time events in Lytics, most
commonly listening to a list of users entering/leaving segments
ie _triggers_.
**Common Use Cases**
* Upon Entering/Leaving you want to send a notification callback with that user data so you can email them, save it, etc.
* Upon Entering Segment, get notified, save an update to a local user-profile so next time they log in, used in your app.
* Upon Entering Segments, get updated with many segments user is member of, and update list of messages user will see next time they logon to app.
**Channels**
Types of streams the event can be delivered.
* *Webhooks*
* *AWS Kinesis*
* *Azure Event-Hub*
* *??? Ask us* Google PubSub.
Some features:
* *withbackfill* this true/false flag to indicate whether to backfill webhook events
for users currently a member of a segment. Default is false, so only new users
entering/exiting a segment would cause a webhook. If you enter withbackfill=true
then all users currently a member of the segment at time of submission would have
a webhook fired for them as well, then changes going forward would start firing.
If backfill is used, only a single segment can be specified.
**Example**
``
export LIOKEY=\"your_api_key\"
export LIODATAKEY=\"your_data_key\"
# UPSERT Segment uses \"ALIAS\" as id for create/update
curl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: text/plain\" \\
-XPOST \"https://api.lytics.io/api/segment\" -d '
-- Paying Users Segment
FILTER AND (
paying_user = \"t\"
)
FROM user
ALIAS demo_segment
' | jq '.'
# get that Segment ID
SEGID=curl -s \"https://api.lytics.io/api/segment?key=$LIOKEY\" | jq -r '.data[] | select(.name == \"demo_segment\") | .id'
echo \"Created Segment id=$SEGID\"
# Create Webhook Subscription to send entry/exits events to your url
# - entry/exits will be sent to the ngrok url below (create your own)
# - we use app-engine for this
echo '
{
\"webhook_url\": \"http://123456abc.ngrok.com/\"
, \"segment_ids\": [\"1234abcd\"]
, \"withbackfill\": false
, \"channel\" : \"webhook\"
, \"name\" : \"webhooktest1\"
, \"description\": \"What is this subscription for?\"
}
' | \\
curl -v -XPOST \"https://api.lytics.io/api/subscription\" \\
-H \"Authorization: $LIOKEY\" \\
-H \"Content-Type: application/json\" -d @- | jq '.'
# for kinesis
curl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: application/json\" \\
-XPOST \"https://api.lytics.io/api/subscription\" -d '
{
\"channel\":\"kinesis\",
\"segment_ids\": [\"1234abcd\",\"abc345\"],
\"name\":\"test2\",
\"description\":\"hello world\",
\"stream\":\"lytics_triggers_stream\",
\"region\": \"us-east-1\",
\"identifier_field\":\"user_id\",
\"role_arn\":\"arn:aws:iam::4444444444444:role/LyticsWriteToKinesis\"
}
' | jq \".\"
# send test data ...
# toggling these next two should move user in/out of segment causing trigger
curl -s -XPOST \"https://api.lytics.io/collect/json/demo\" -H \"Authorization: $LIODATAKEY\" -H 'Content-type: application/json' \\
-d '{ \"paying_user\":\"f\", \"user_id\":\"user123\"}' | jq '.'
curl -s -XPOST \"https://api.lytics.io/collect/json/demo\" -H \"Authorization: $LIODATAKEY\" -H 'Content-type: application/json' \\
-d '{ \"paying_user\":\"t\", \"user_id\":\"user123\"}' | jq '.'
`
**Webhook Post Example**
This will send a json document like below to your subscription channel.
But, this is a **BETA API** and this will change. We
received feedback that the more logical set of data
is all segment changes (not just one per subscription) so we
are modifying the response to be an array of segment entry/exits.
## Example Message
There are still message format from v1 of this api to
maintain backwards compatibility.
`
{
\"data\": {
\"_created\": \"2016-06-29T18:50:16.902758229Z\",
\"_modified\": \"2017-03-18T06:12:36.829070108Z\",
\"email\": \"testwebhook@lytics.io\",
\"user_id\": \"user123\",
\"segment_events\":[
{
\"id\": \"d3d8f15855b6b067709577342fe72db9\",
\"event\": \"exit\",
\"enter\": \"2017-03-02T06:12:36.829070108Z\",
\"exit\": \"2017-03-18T06:12:36.829070108Z\",
\"slug\": \"demo_segment\"
},
{
\"id\": \"abc678asdf\",
\"event\": \"enter\",
\"enter\": \"2017-03-02T06:12:36.829070108Z\",
\"exit\": \"2099-03-18T06:12:36.829070108Z\",
\"slug\": \"another_segment\"
}
]
},
\"meta\":{
\"object\":\"user\",
\"source\":\"subscription\",
\"subscription_id\": \"7e2b8804bbe162cd3f9c0c5991bf3078\"
}
}
``
" url: "https://www.contentstack.com/docs/developers/apis/lytics-api/v1/subscription" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-11-05" --- # Subscription \*\*BETA API\*\* Subscriptions are queries into real-time events in Lytics, most commonly listening to a list of users entering/leaving segments ie \_triggers\_. \*\*Common Use Cases\*\* \* Upon Entering/Leaving you want to send a notification callback with that user data so you can email them, save it, etc. \* Upon Entering Segment, get notified, save an update to a local user-profile so next time they log in, used in your app. \* Upon Entering Segments, get updated with many segments user is member of, and update list of messages user will see next time they logon to app. \*\*Channels\*\* Types of streams the event can be delivered. \* \*Webhooks\* \* \*AWS Kinesis\* \* \*Azure Event-Hub\* \* \*??? Ask us\* Google PubSub. Some features: \* \*withbackfill\* this true/false flag to indicate whether to backfill webhook events for users currently a member of a segment. Default is false, so only new users entering/exiting a segment would cause a webhook. If you enter withbackfill=true then all users currently a member of the segment at time of submission would have a webhook fired for them as well, then changes going forward would start firing. If backfill is used, only a single segment can be specified. \*\*Example\*\* \`\` export LIOKEY="your\_api\_key" export LIODATAKEY="your\_data\_key" \# UPSERT Segment uses "ALIAS" as id for create/update curl -s -H "Authorization: $LIOKEY" -H "Content-Type: text/plain" \\ \-XPOST "https://api.lytics.io/api/segment" -d ' \-- Paying Users Segment FILTER AND ( paying\_user = "t" ) FROM user ALIAS demo\_segment ' | jq '.' \# get that Segment ID SEGID=curl -s "https://api.lytics.io/api/segment?key=$LIOKEY" | jq -r '.data\[\] | select(.name == "demo\_segment") | .id' echo "Created Segment id=$SEGID" \# Create Webhook Subscription to send entry/exits events to your url \# - entry/exits will be sent to the ngrok url below (create your own) \# - we use app-engine for this echo ' { "webhook\_url": "http://123456abc.ngrok.com/" , "segment\_ids": \["1234abcd"\] , "withbackfill": false , "channel" : "webhook" , "name" : "webhooktest1" , "description": "What is this subscription for?" } ' | \\ curl -v -XPOST "https://api.lytics.io/api/subscription" \\ \-H "Authorization: $LIOKEY" \\ \-H "Content-Type: application/json" -d @- | jq '.' \# for kinesis curl -s -H "Authorization: $LIOKEY" -H "Content-Type: application/json" \\ \-XPOST "https://api.lytics.io/api/subscription" -d ' { "channel":"kinesis", "segment\_ids": \["1234abcd","abc345"\], "name":"test2", "description":"hello world", "stream":"lytics\_triggers\_stream", "region": "us-east-1", "identifier\_field":"user\_id", "role\_arn":"arn:aws:iam::4444444444444:role/LyticsWriteToKinesis" } ' | jq "." \# send test data ... \# toggling these next two should move user in/out of segment causing trigger curl -s -XPOST "https://api.lytics.io/collect/json/demo" -H "Authorization: $LIODATAKEY" -H 'Content-type: application/json' \\ \-d '{ "paying\_user":"f", "user\_id":"user123"}' | jq '.' curl -s -XPOST "https://api.lytics.io/collect/json/demo" -H "Authorization: $LIODATAKEY" -H 'Content-type: application/json' \\ \-d '{ "paying\_user":"t", "user\_id":"user123"}' | jq '.' \` \*\*Webhook Post Example\*\* This will send a json document like below to your subscription channel. But, this is a \*\*BETA API\*\* and this will change. We received feedback that the more logical set of data is all segment changes (not just one per subscription) so we are modifying the response to be an array of segment entry/exits. \## Example Message There are still message format from v1 of this api to maintain backwards compatibility. \` { "data": { "\_created": "2016-06-29T18:50:16.902758229Z", "\_modified": "2017-03-18T06:12:36.829070108Z", "email": "testwebhook@lytics.io", "user\_id": "user123", "segment\_events":\[ { "id": "d3d8f15855b6b067709577342fe72db9", "event": "exit", "enter": "2017-03-02T06:12:36.829070108Z", "exit": "2017-03-18T06:12:36.829070108Z", "slug": "demo\_segment" }, { "id": "abc678asdf", "event": "enter", "enter": "2017-03-02T06:12:36.829070108Z", "exit": "2099-03-18T06:12:36.829070108Z", "slug": "another\_segment" } \] }, "meta":{ "object":"user", "source":"subscription", "subscription\_id": "7e2b8804bbe162cd3f9c0c5991bf3078" } } \`\` ## SubscriptionList ### SubscriptionList **GET** `/api/subscription` Get A list of all Subscriptions. \`\`sh \# find subscriptions that contain a specific segment.Id or segment.Slug curl -s -H "Authorization: $LIOKEY" -H "Content-Type: application/json" \\ "https://api.lytics.io/api/subscription?segment\_id=seg\_webhook1" | jq "." \# same but use id. curl -s -H "Authorization: $LIOKEY" -H "Content-Type: application/json" \\ "https://api.lytics.io/api/subscription?segment\_id=f897270369f977294871f21cc0d826e7" | jq "." \`\` #### Query Parameters - **account_id** (optional) Your Lytics account ID. - **segment_id** (optional) Id of Segment Id OR Slug to filter on - **table** (optional) Table name. #### Headers - **Authorization** (optional) #### Sample Response ```json { "data": [ { "id": "3573009ab39bbc9614f754c0fafd53d7", "segment_ids": [ "f897270369f977294871f21cc0d826e7" ], "segmentql": "FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1", "description": "hello world", "name": "test1", "updated": "2016-06-30T15:33:14.376262062-07:00", "created": "2016-06-30T15:33:14.37626196-07:00", "user_id": "2916b84ba4fa8b510591fd6e1c2320db", "account_id": "testid", "workflow": "webhook_triggers" } ] } ``` ## Subscription Upsert ### Subscription Upsert **POST** `/api/subscription` Upsert a new Subscription. Subscriptions allow you to listen and recieve notification of events inside of Lytics, most common would be listen to users entering/leaving segments to serve as triggers. When creating subscriptions they have the following fields. | field | DataType | Description | |---------------|------------------|---------------| | channel | string | Required: What Type of subscription. \[kinesis, webhook\] | name | string | Name of this Subscription | description | string | Long text description (optional) | segment\_ids | \[\]string | List of segment Ids | withbackfill | bool | Should all members of this segment be included? They will be marked as "entered" segment. \*Webhook\* only fields: | field | DataType | Description | |---------------|-------------------|---------------| | webhook\_url | string | Required for Webhooks, only used on webhooks, url to post to. | headers | map\[string\]string | Optional map of headers to send with webhook | segmentio\_writekey | string | Optional api key for sending to segment.io \*Kinesis\* only fields: | field | DataType | Description | |------------------|------------------|---------------| | region | string | Required. AWS Region | stream | string | Required. Kinesis stream | role\_arn | string | AWS IAM Role to use for assume-role (see integrations doc) | identifier\_field | string | Optional. If provided, pull this field from user field and use as shard-key in Kinesis Put. Create a Webhook Subscription that includes the Segment definition and custom headers (optional) \`\`sh curl -s -H "Authorization: $LIOKEY" -H "Content-Type: application/json" \\ \-XPOST "https://api.lytics.io/api/subscription" -d ' { "segmentql": "FILTER AND ( score\_momentum > 25, score\_quantity > 25 ) ALIAS seg\_webhook1", "name":"test1", "channel" : "webhook", "description":"hello world", "webhook\_url":"https://demo.appspot.com/log", "headers": {"Authorization": "dGhpczp0aGF0"} } ' | jq "." \` Create a Webhook subscription with list of SegmentId's (previously created) to listen to. \` curl -s -H "Authorization: $LIOKEY" -H "Content-Type: application/json" \\ \-XPOST "https://api.lytics.io/api/subscription" -d ' { "segment\_ids": \["1234abcd","abc345"\], "channel":"webhook", "name":"test2", "description":"hello world", "webhook\_url":"https://demo.appspot.com/log" } ' | jq "." \` Create a Kinesis Subscription \` curl -s -H "Authorization: $LIOKEY" -H "Content-Type: application/json" \\ \-XPOST "https://api.lytics.io/api/subscription" -d ' { "channel":"kinesis", "segment\_ids": \["1234abcd","abc345"\], "name":"test2", "description":"hello world", "stream":"lytics\_triggers\_stream", "region": "us-east-1", "identifier\_field":"user\_id", "role\_arn":"arn:aws:iam::4444444444444:role/LyticsWriteToKinesis" } ' | jq "." \`\` #### Query Parameters - **account_id** (optional) Your Lytics account ID. #### Headers - **Authorization** (optional) #### Sample Response ```json { "data": { "id": "3573009ab39bbc9614f754c0fafd53d7", "segment_ids": [ "f897270369f977294871f21cc0d826e7" ], "segmentql": "FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1", "description": "hello world", "name": "test1", "updated": "2016-06-30T15:33:14.376262062-07:00", "created": "2016-06-30T15:33:14.37626196-07:00", "user_id": "2916b84ba4fa8b510591fd6e1c2320db", "account_id": "testid", "workflow": "webhook_triggers" } } ``` ## Subscription Fetch ### Subscription Fetch **GET** `/api/subscription/{id}` Get a single Subscription Webhook. #### URL Parameters - **id** (required) subscription Id in path #### Query Parameters - **account_id** (optional) Your Lytics account ID. #### Headers - **Authorization** (optional) #### Sample Response ```json { "data": { "id": "3573009ab39bbc9614f754c0fafd53d7", "segment_ids": [ "f897270369f977294871f21cc0d826e7" ], "segmentql": "FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1", "description": "hello world", "name": "test1", "updated": "2016-06-30T15:33:14.376262062-07:00", "created": "2016-06-30T15:33:14.37626196-07:00", "user_id": "2916b84ba4fa8b510591fd6e1c2320db", "account_id": "testid", "workflow": "webhook_triggers" } } ``` ## Subscription Delete ### Subscription Delete **DELETE** `/api/subscription/{id}` Delete A Subscription. #### URL Parameters - **id** (required) subscription Id in path #### Query Parameters - **account_id** (optional) Your Lytics account ID. #### Headers - **Authorization** (optional) #### Sample Response ```json No Content ```