> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data streams: set up a subscription

> Create a subscription in Lobyco Nexus, choose its events, hand over the signing key, test it and switch it on.

Data streams send Lobyco events to your own system as they happen, for example to a CDP, a CRM or a data platform. This guide is for the integration admin who sets up the subscription in Lobyco Nexus.

> [!NOTE]
>
> A data stream is not a block on the campaign canvas, and it does not change how campaigns run. To call your system at one step of one campaign, use the [OutboundAPI connection](https://help.lobyco.com/integration/external-integrations/outboundapi-connection.md) instead.

## Before you start

* **Access to Data streams.** You need the Data streams admin role. [Nexus roles](https://help.lobyco.com/integration/get-started/admin-portal-roles.md#data-streams) lists it, with the read-only role.
* **A callback URL.** This is the HTTPS address in the receiving system that accepts the events. It must use a public host name. Nexus refuses an IP address and an address in a private network.
* **An auth integration.** Lobyco always signs in to the receiving system, with OAuth 2.0 client credentials, HTTP Basic or custom headers. You can pick a saved integration or create one from the subscription form. [Authentication](https://help.lobyco.com/integration/external-integrations/outboundapi-connection.md#authentication) describes the three types.
* **The receiving system's developer.** They build the endpoint by following [Data streams: receive webhooks](https://help.lobyco.com/integration/external-integrations/data-streams/receive-webhooks.md). You give them the signing key during this guide.

## Set up a subscription

**Step 1**

### Open the subscription list

In Nexus, go to **Data & integrations → Data streams**. Each row is a subscription: one callback URL and the events sent to it. The list shows each subscription's events, its status, its auth type, when it last changed and its owner.

![The Data streams list under Data & integrations with two subscriptions. Marketing platform – welcome journey sends member.signed\_up, is Disabled and uses OAuth 2.0. CDP – offer journeys sends offer.assigned, offer.activated and offer.redeemed, is Enabled and uses OAuth 2.0. Each row shows when it last changed, its owner and a menu. The New subscription button is at the top right.](https://mintcdn.com/lobyco-4c9fb3ad/_1vHz9uhvbRKvteU/images/external-integrations-01-data-streams-list.png?fit=max\&auto=format\&n=_1vHz9uhvbRKvteU\&q=85\&s=587c76fbe216bb925cb8b8b4b70afb6c)

*The Data streams list*

Select **New subscription**.

**Step 2**

### Fill in the subscription details

On the **Subscription details** tab, fill in four fields:

* **Name**: how your team recognises the subscription, for example the receiving system and what it uses the events for.
* **Description**: optional. What the subscription is for.
* **Callback URL**: the receiving system's HTTPS address for the events.
* **Auth integration**: the credentials Lobyco signs in with. The field reads **No auth** until you choose one, and you must choose one.

To add credentials without leaving the form, select **Create new auth integration**. The **Test** button beside the field sends a connection test once the subscription is saved.

![The Subscription details tab of a new subscription: Name CDP – offer journeys, Description Offer events for customer journeys in the CDP, Callback URL https://cdp.example.com/webhooks/lobyco and Auth integration Customer data platform, with a Test button and a Create new auth integration button beside it. Save and Enable are disabled because no event is selected yet.](https://mintcdn.com/lobyco-4c9fb3ad/_1vHz9uhvbRKvteU/images/external-integrations-02-data-streams-subscription-details.png?fit=max\&auto=format\&n=_1vHz9uhvbRKvteU\&q=85\&s=87bc2f01228a503b4a31d8ec488e368f)

*A new subscription, Subscription details tab*

**Save** and **Enable** stay greyed out until you select at least one event. Several subscriptions can use the same callback URL. Each one has its own signing key and its own deliveries.

**Step 3**

### Select the events

Open the **Events** tab. It lists the events you can choose, each with a description and a **Category**:

* **Definition**: a campaign, an Inbound API block, an offer, a challenge or a game was created, changed, published, stopped or deleted.
* **Engagement**: something happened for one customer, such as an offer being redeemed.
* **Member**: a member's profile, consents or loyalty cards changed.

Select the events the receiving system uses. For example:

* A CDP starts a journey when a customer gets an offer: `offer.assigned`.
* A CRM stops reminders once the customer has redeemed: `offer.redeemed`.
* A marketing platform starts a welcome journey for each new member: `member.signed_up`.
* A data platform keeps its copy of offers and challenges up to date: `offer.*` and `challenge.*` definition events.

The [Events](https://help.lobyco.com/integration/external-integrations/events) catalogues list each event's Data streams type, availability, timing and schema. Check the [personal-data warning](https://help.lobyco.com/integration/external-integrations/events/customer-events.md) before selecting customer events.

![The Events tab of a new subscription, listing each event with its description and category. offer.assigned (A coupon was created for a customer), offer.activated (A customer activated a coupon) and offer.redeemed (A coupon was redeemed), all Engagement, are selected. offer.published, offer.stopped, offer.deleted and the challenge events, all Definition, are not. Every row has a Configure payload link.](https://mintcdn.com/lobyco-4c9fb3ad/_1vHz9uhvbRKvteU/images/external-integrations-03-data-streams-events-selected.png?fit=max\&auto=format\&n=_1vHz9uhvbRKvteU\&q=85\&s=1bd36e5c1f969fed0450d3b1a22a194d)

*The Events tab with three offer events selected*

**Step 4**

### \[Optional] Configure a payload

By default, Lobyco sends each event exactly as its owning service publishes it. To send your own JSON instead, select **Configure payload** on the event's row. Write the JSON in the **Payload transformation** editor, with a placeholder such as `{{ event.OfferId }}` for each field.

When you type `{{ event.`, the editor suggests the event's fields. **View schema** describes them. [Write a payload transformation](#write-a-payload-transformation) has the rules.

![The Payload transformation editor open under the offer.redeemed row on the Events tab. It holds a JSON object with type coupon\_redeemed, customer \{\{ event.CustomerId }}, offer \{\{ event.OfferId }}, store \{\{ event.StoreId }} and source lobyco. A View schema link and a Test payload button sit above the editor; Test payload is disabled until the subscription is saved.](https://mintcdn.com/lobyco-4c9fb3ad/_1vHz9uhvbRKvteU/images/external-integrations-04-data-streams-payload-transformation.png?fit=max\&auto=format\&n=_1vHz9uhvbRKvteU\&q=85\&s=c2b4606432ec815a4d14183761058497)

*The payload transformation for offer.redeemed*

**Step 5**

### Save and copy the signing key

Select **Save**. Nexus saves the subscription **disabled**, so nothing is sent yet. It then shows the subscription's signing key in the **Your subscription was saved** dialog.

Select **Copy** and send the key securely to the receiving system's developer, for example through a password manager. The key is shown only once. When you open the subscription later, Nexus shows only when the key was last generated.

![The Your subscription was saved dialog after saving a new subscription. It reads: Use this key to verify that events come from Lobyco and were not altered. It is shown only once, but you can generate a new one at any time. The key is blurred, with a Copy button beside it and a Close button below.](https://mintcdn.com/lobyco-4c9fb3ad/_1vHz9uhvbRKvteU/images/external-integrations-05-data-streams-signing-key.png?fit=max\&auto=format\&n=_1vHz9uhvbRKvteU\&q=85\&s=c8f88247ff660d9d1de7ffc493ee8c33)

*The signing key, shown once after saving*

> [!WARNING]
>
> **Save first, then enable.** **Enable** on a new subscription saves and enables it in one go, and shows the key as well. Events then go out at once, before the receiving system has the key. If the receiver rejects them, for example with `401`, Lobyco does not retry them. It sets them aside instead.

**Step 6**

### Test the subscription

A test uses the subscription as it was last saved. It works whether the subscription is enabled or disabled.

* **Test the connection.** Select **Test** beside **Auth integration**, or **Test** in the subscription's menu in the list. Lobyco sends one small test event to the callback URL, signed and authenticated like a real event.
* **Test one event.** On the **Events** tab, select **Configure payload** on a selected event, then **Test payload**. Lobyco sends a sample of that event, with made-up values, through its saved payload transformation. Nexus shows the **Payload sent**. Under **Not in the event sample (sent empty)**, it lists placeholders the event does not carry.

Nexus then shows how the receiving system answered: **Success** or **Failure**, the status code, the response time, any error and the start of the response. A `2xx` answer means the address is reachable and accepts the credentials. If the receiver already checks signatures, it also means the key reached the developer intact.

The receiving system recognises test events by their type, `webhook.test`: see [Recognise test requests](https://help.lobyco.com/integration/external-integrations/data-streams/receive-webhooks.md#recognise-test-requests).

**Step 7**

### Enable the subscription

When the tests succeed and the developer confirms the receiver is ready, select **Enable**.

The list now shows the subscription as **Enabled**. Lobyco sends every matching event from this moment on, as it happens. Events from before you enabled the subscription are not sent.

## Write a payload transformation

A payload transformation replaces the event body with your own JSON, built from the event's fields. You can pick fields, rename them, nest them and add fixed values. It is set per event, and it is optional.

For example, for `offer.redeemed`:

```json theme={"system"}
{
  "type": "coupon_redeemed",
  "customer": "{{ event.CustomerId }}",
  "offer": "{{ event.OfferId }}",
  "store": "{{ event.StoreId }}",
  "source": "lobyco"
}
```

The receiving system then gets this JSON as the body, with each placeholder replaced by the value from the event.

Write the values this way:

* **In quotes, a value arrives as text.** `"{{ event.OfferId }}"` works for every field. A true or false field in quotes arrives as the text `"true"` or `"false"`.
* **Without quotes, a number or a true or false field keeps its type.** `"points": {{ event.Points }}` sends a number. Use this only for a field every event carries: an empty value without quotes breaks the JSON, and the event is not sent. Text always goes in quotes.
* **An empty field arrives empty.** A field the event leaves out, or sends as `null`, arrives as `""` in quotes.
* **Only plain JSON with placeholders.** The editor refuses filters such as `| date` and `| default`, and tags such as `{% if %}` and `{% for %}`.
* **Prefer ids, codes and dates to free text.** A value that contains quotes, backslashes or line breaks breaks the JSON.

When you save, Nexus checks every transformation:

* **Invalid JSON**: the payload is not valid JSON once its placeholders are filled in.
* **Unavailable tags are used**: a placeholder names a field the event does not have, or uses a filter.

A transformation reshapes the event's own fields only. It cannot add data the event does not carry, such as customer details. Anyone who can view the subscription can read its transformations, so never put passwords or keys in them.

Clearing the editor removes the transformation, and so does deselecting the event. The event is then sent as published again.

## Manage a subscription

| Action | What happens |
| - | - |
| Change and **Save** | A new callback URL, auth integration, event or payload applies within about a minute. |
| **Generate new key** | Nexus shows a new signing key once. The previous key keeps working for 24 hours, so the receiving system can switch without rejecting deliveries. |
| **Generate new key** twice | Use this when a key has leaked. The oldest key stops working at once. Give the receiving system the key shown last. |
| **Disable** | Nexus asks you to confirm, saves your changes and stops sending. Events waiting for delivery, retries included, are discarded. Enabling again does not resend them. |
| **Enable** | Lobyco sends matching events from this moment on. Nothing from the disabled period is sent. |
| **Delete** | Removes the subscription for good. Disable it first. |

An auth integration can be shared. An Outbound API block and a data stream can use the same one. A colleague who edits it may not see that a subscription depends on it. A wrong change makes the deliveries fail until it is fixed.

> [!WARNING]
>
> **Deleting an auth integration does not stop its data streams.** The subscriptions that use it keep signing in with it. To stop them, disable each one, or switch it to another integration. While a subscription uses a deleted integration, its callback URL cannot be changed.

## Failure and edge cases

> [accordion] Data streams is not in the menu
>
> Data streams appear only for users with a [Data streams role](https://help.lobyco.com/integration/get-started/admin-portal-roles.md#data-streams), and only where Data streams are switched on. Your Lobyco contact can switch them on.

> [accordion] Save and Enable are greyed out
>
> Select at least one event on the **Events** tab. With read-only access, every action stays greyed out.

> [accordion] Test payload is greyed out
>
> Save the subscription first. A test always uses the saved version.

> [accordion] The test fails
>
> Read the status code and the error that Nexus shows. A `401` or `403` means the receiving system refused the credentials: check the auth integration. A timeout or a connection error means the address did not answer: check the callback URL. Each attempt has 10 seconds in total, including the sign-in.

> [accordion] The signing key was lost
>
> Select **Generate new key** and give the new key to the developer, as in [Manage a subscription](#manage-a-subscription).

> [accordion] The receiving system is down for a while
>
> Leave the subscription enabled. Lobyco keeps retrying each event on its [retry schedule](https://help.lobyco.com/integration/external-integrations/data-streams/receive-webhooks.md#failure-and-edge-cases). Disabling the subscription discards every event that is waiting.

> [accordion] An event never arrived
>
> Nexus has no delivery history, and you cannot resend events yourself. Events that could not be delivered are kept for 30 days. Lobyco Support can look them up and resend them once the cause is fixed.

## Related

* [Data streams: receive webhooks](https://help.lobyco.com/integration/external-integrations/data-streams/receive-webhooks.md) — what the receiving system's developer builds: signature check, responses, retries and duplicates.
* [Events](https://help.lobyco.com/integration/external-integrations/events) — event types, Data streams availability, timing and JSON Schemas.
* [OutboundAPI connection](https://help.lobyco.com/integration/external-integrations/outboundapi-connection.md) — the three auth integration types, and how to call your system at one step of a campaign instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.