---
title: "Subscription Upsert"
method: POST
path: "/api/subscription"
tags: ["Subscription"]
---

# Subscription Upsert

`POST /api/subscription`

## Request

- Base URL: `https://api.lytics.io`
- URL: `https://api.lytics.io/api/subscription`
- Auth: API key in header `Authorization`

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` string

## Request body

- object
  - `segment_ids` string[]
  - `name` string
  - `channel` string
  - `withbackfill` boolean
  - `description` string
  - `webhook_url` string

## Response `200`

OK

- SubscriptionModel
  - `data` object
    - `id` string
    - `segment_ids` string[]
    - `segmentql` string
    - `description` string
    - `name` string
    - `updated` string
    - `created` string
    - `user_id` string
    - `account_id` string
    - `workflow` string

---

[API](https://skmtc.dev/lytics/apis/v1-lytics-api.md) - [All operations](https://skmtc.dev/lytics/apis/v1-lytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lytics/apis/v1-lytics-api/revisions/339fd1d88486?raw)