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.

Before you start

Your backend must be able to authenticate with the Crisp REST API. Start with the 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.

Create the event payload

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

{
  "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.

Send the event to the REST API

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

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

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.

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

Updated on: 03/05/2026

Was this article helpful?

Thank you!