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": "[email protected]",

"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"

}

}

``