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 Segments, 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="{API Token}"

# 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": "https://somewebhook.com/test"
    , "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: $LIOKEY"  -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: $LIOKEY"  -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"
  }
}

Subscription List

/api/subscription

Get all current subscriptions.

# find subscription(s) that reference a segment (by slug)
curl -s -H "Authorization: $LIOKEY" \
    "https://api.lytics.io/api/subscription?segment_id=known_users_not_customer" | jq '.'

# find subscription(s) that contain a segment (by id)
curl -s -H "Authorization: $LIOKEY" \
    "https://api.lytics.io/api/subscription?segment_id=f9e314d7de3a4c9c119667b85700c636" | jq '.'

GET

Subscription List

/api/subscription

Get all Subscriptions.

Parameters
segment_id	string (optional) Ex: 1234	include only subscriptions which reference this segment (id or slug)

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "id": "3573009ab39bbc9614f754c0fafd53d7",
        "segment_ids": [
            "f897270369f977294871f21cc0d826e7"
        ],
        "segmentql": "FILTER AND ( score_momentum \u003e 25, score_quantity \u003e 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",
        "config": {
            "channel": "webhook",
            "description": "hello world",
            "headers": {
                "Authorization": "{API Token}",
                "best_number": "47"
            },
            "name": "test1",
            "segment_ids": [
            "920242cc56300cacba02e44f7775be99"
            ],
            "segmentql": "FILTER AND ( score_momentum \u003e 25, score_quantity \u003e 25 ) ALIAS seg_webhook1",
            "webhook_url": "http://lytics-dev.appspot.com/47"
        },
    }
}

Subscription

/api/subscription/{id}

Get a single Subscription resource.

Parameters
id	string (required) Ex: 1234	subscription Id in path

GET

Subscription Fetch

/api/subscription/{id}

Get a single Subscription Webhook.

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "id": "3573009ab39bbc9614f754c0fafd53d7",
        "segment_ids": [
            "f897270369f977294871f21cc0d826e7"
        ],
        "segmentql": "FILTER AND ( score_momentum \u003e 25, score_quantity \u003e 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",
        "config": {
            "channel": "webhook",
            "description": "hello world",
            "headers": {
                "Authorization": "{API Token}",
                "best_number": "47"
            },
            "name": "test1",
            "segment_ids": [
            "920242cc56300cacba02e44f7775be99"
            ],
            "segmentql": "FILTER AND ( score_momentum \u003e 25, score_quantity \u003e 25 ) ALIAS seg_webhook1",
            "webhook_url": "https://somewebhook.com/test"
        },
    }
}

POST

Subscription Upsert

/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)

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://somewebhook.com/test",
    "headers": {"Authorization": "{API Token}"}
}
' | 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://somewebhook.com/test"
}
' | 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 "."

Request

Headers

Content-Type: application/json

Body

{
    "segment_ids": ["1234abcd","abc345"],
    "name":"test2",
    "channel": "webhook",
    "withbackfill":false,
    "description":"hello world",
    "webhook_url":"https://somewebhook.com/test"
}

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "id": "3573009ab39bbc9614f754c0fafd53d7",
        "segment_ids": [
            "f897270369f977294871f21cc0d826e7"
        ],
        "segmentql": "FILTER AND ( score_momentum \u003e 25, score_quantity \u003e 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",
        "config": {
            "channel": "webhook",
            "description": "hello world",
            "headers": {
                "Authorization": "{API Token}",
                "best_number": "47"
            },
            "name": "test1",
            "segment_ids": [
            "920242cc56300cacba02e44f7775be99"
            ],
            "segmentql": "FILTER AND ( score_momentum \u003e 25, score_quantity \u003e 25 ) ALIAS seg_webhook1",
            "webhook_url": "https://somewebhook.com/test"
        },
    }
}

DELETE

Subscription Delete

/api/subscription/{id}

Delete A Subscription.

Subscription

Example Message

Subscription List

Subscription List

Response 200

Headers

Body

Subscription

Subscription Fetch

Response 200

Headers

Body

Subscription Upsert

Request

Headers

Body

Response 200

Headers

Body

Subscription Delete

Response 204

Segment Collection

Personalization