> For the complete documentation index, see [llms.txt](https://help.usejimo.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.usejimo.com/docs/integrations/server-side-events.md).

# Server-side events

Send identify and track events from your backend to Jimo through one API endpoint, to update user attributes and record actions that happen outside the browser.

Server-side events let your backend send data to Jimo directly. Use them for what happens outside the browser, such as a payment, a plan change or an import finishing, and for attributes your front-end does not know.

{% hint style="info" %}
Server-side events are in beta. If you have any questions, contact us at <support@usejimo.com>.
{% endhint %}

## When to use it

| You want to send                              | Use                                                                                                                   |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Attributes and events your front-end knows    | The SDK: [Attributes and events](https://help.usejimo.com/docs/getting-started/install-jimo/attributes-and-events.md) |
| Attributes and events only your backend knows | Server-side events                                                                                                    |
| Data already flowing through Segment          | [Segment](https://help.usejimo.com/docs/integrations/segment.io.md), server-side destination                          |

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FHAzKX2jkj6Akgx8m9XgP%2FF2-55-server-side-events-flow.png?alt=media&amp;token=69c5f45d-c226-4ce5-aa4e-8d98d73c656a" alt="Your backend posts identify and track calls to the server-side events endpoint with the x-api-key header; identify updates attributes on the user, track records an event listed in Success Tracker > Events. The userId must match the one used in identify"><figcaption></figcaption></figure>

## Before you start

* A backend that can send HTTP requests.
* Your API key, from [Settings > Integrations > Server-Side Events](https://i.usejimo.com/settings/integrations/sse): the key is masked, copy it with the copy button next to it. Keep it on your server: never ship it in front-end code.
* The ID you use for each user in Jimo's identify call. Server-side events must use the same value. See [Identify your users](https://help.usejimo.com/docs/getting-started/install-jimo/identify-your-users.md).

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FMyzkkxY6h14UIR2zcLE7%2FF2-17-server-side-events.png?alt=media&amp;token=8e1ef464-bfb6-49d4-aa51-96ab0420d9f4" alt="Server-Side Events settings page in Jimo, with the Server-Side Events in BETA notice. A: the API key, masked. B: the copy button."><figcaption></figcaption></figure>

## Endpoint and authentication

|                |                                                   |
| -------------- | ------------------------------------------------- |
| URL            | `https://karabor-harbour.usejimo.com/sse/webhook` |
| Authentication | Your API key in the `x-api-key` request header    |
| Event types    | `identify`, `track`                               |

## Identify: update user attributes

| Field       | Type   | Required | Description                                                      |
| ----------- | ------ | -------- | ---------------------------------------------------------------- |
| `userId`    | string | Yes      | The user's ID, the same value as the identify token used in Jimo |
| `type`      | string | Yes      | `identify`                                                       |
| `timestamp` | string | Yes      | ISO-8601, in UTC                                                 |
| `traits`    | object | Yes      | Key-value pairs of attributes to update                          |

```json
{
  "userId": "12345",
  "type": "identify",
  "timestamp": "2024-01-01T12:00:00Z",
  "traits": {
    "plan": "premium",
    "signup_date": "2023-06-15"
  }
}
```

The keys of `traits` are attribute keys. Create them in [Attributes](https://help.usejimo.com/docs/analyze/users-and-segments/data-management/attributes.md) with their type before you send values, so segments can use them from the first call. See [Create a custom attribute](https://help.usejimo.com/docs/analyze/users-and-segments/data-management/attributes/create-a-custom-attribute.md).

## Track: record an action

| Field        | Type   | Required | Description                                                      |
| ------------ | ------ | -------- | ---------------------------------------------------------------- |
| `userId`     | string | Yes      | The user's ID, the same value as the identify token used in Jimo |
| `type`       | string | Yes      | `track`                                                          |
| `timestamp`  | string | Yes      | ISO-8601, in UTC                                                 |
| `event`      | string | Yes      | The name of the event                                            |
| `properties` | object | No       | Key-value pairs with details on the event                        |

```json
{
  "userId": "12345",
  "type": "track",
  "timestamp": "2024-01-01T12:05:00Z",
  "event": "button_clicked",
  "properties": {
    "button_name": "Subscribe",
    "page": "pricing"
  }
}
```

Name events the same way as your SDK events, so one event name means one action wherever it comes from.

## Verify

1. Send an `identify` call for a test user, then open that user in [Users](https://help.usejimo.com/docs/analyze/users-and-segments/audience/users.md) and check the attributes.
2. Send a `track` call, then check that the event is listed in [Success Tracker > Events](https://help.usejimo.com/docs/analyze/success-tracker/events.md). The list shows each event once, with its **Source** and when it was **Last received at**, not a history over time: to follow an event over time, create a feature usage [tracker](https://help.usejimo.com/docs/analyze/success-tracker/trackers.md).

<figure><img src="https://2794860263-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKzAcDWQbK1gKbpra7bkb%2Fuploads%2FHQ6OzATEzsI5Ysw2PSZd%2FF2-03-incoming-event.png?alt=media&amp;token=cb7ffdec-4caf-4022-aa84-a47bec0e0c71" alt="Success Tracker > Events, with the columns Name, Source, Created at and Last received at. The row of an event received from Segment is outlined, and A marks its Source."><figcaption></figcaption></figure>

## Limits

#### Backend only

The API key gives write access to your users' data: keep it on your server, never in front-end code.

#### Events are listed, not counted

Success Tracker > Events lists each event once, with its **Source** and when it was **Last received at**, not a history over time. To follow an event over time, create a feature usage [tracker](https://help.usejimo.com/docs/analyze/success-tracker/trackers.md).

## Common mistakes

#### The user is not updated

The `userId` does not match the ID used in Jimo's identify call. Use the exact same value, with the same format.

#### Dates look shifted

Send ISO-8601 timestamps in UTC.

## Related

* [Attributes](https://help.usejimo.com/docs/analyze/users-and-segments/data-management/attributes.md): the list of attributes and their types
* [Identify your users](https://help.usejimo.com/docs/getting-started/install-jimo/identify-your-users.md)
* [SDK methods](https://help.usejimo.com/docs/for-developers/for-developers/sdk-methods.md): the front-end equivalent, `event:track` and `user:attributes`
* [Webhooks](https://help.usejimo.com/docs/integrations/webhooks.md): the opposite direction, from Jimo to your backend
