> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.crisp.chat/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How to push user events from your backend

*Learn how to add a people event to a Crisp profile from your backend.*

Crisp can receive custom events from the chatbox, but backend events are often better for server-side actions such as purchases, invoices, order updates, trial changes, or account milestones.

---

# ${color}[#0080dd](Before you start)

Your backend must be able to authenticate with the Crisp REST API. Start with the [REST API quickstart](https://docs.crisp.chat/guides/rest-api/quickstart/) and keep your API credentials server-side.

__You will need:__
* Your **website_id**
* The user's **people_id** or email address
* A valid event payload
* API credentials with access to people events

|| The **people_id** is the stable Crisp profile identifier. The REST API also allows you to pass the person's email address as the `people_id` value, which is often easier if your system already stores user emails.

---

# ${color}[#0080dd](Create the event payload)

A people event contains a required **text** value, plus optional **color** and **data** values.

```json
{
  "text": "basket:item:added",
  "color": "blue",
  "data": {
    "product": "iPhone X"
  }
}
```

Use a consistent naming convention for **text**, such as `order:created`, `trial:started`, or `subscription:upgraded`. This makes events easier to read and filter later.

---

# ${color}[#0080dd](Send the event to the REST API)

Submit the event payload with an HTTP `POST` request to this route:

```text
/v1/website/{website_id}/people/events/{people_id}
```

For example, if your website ID is `04ed9a29-ccda-4f46-b2f3-b151d2d90fa7` and the profile email is `john.doe@crisp.chat`, the full URL would be:

```text
https://api.crisp.chat/v1/website/04ed9a29-ccda-4f46-b2f3-b151d2d90fa7/people/events/john.doe@crisp.chat
```

| The route is documented in the [Add a people event REST API reference](https://docs.crisp.chat/references/rest-api/v1/#add-a-people-event).

---

# ${color}[#0080dd](Use clean event data)

People events are useful when they remain readable for your team. Keep event names short, avoid sensitive information, and use the **data** object for useful context only.

__Good event data usually follows these rules:__
* **Readable text** → agents can quickly understand what happened
* **Stable keys** → the same type of event always uses the same data fields
* **Minimal payload** → only include values that are useful for support, sales, or automation
* **No secrets** → never send passwords, access tokens, payment credentials, or private security data