REST API reference

Events

Track what people do in your product to target messages, trigger workflows and give context.

Events show up on the person’s activity timeline and power segments (event.<name>.count rules), outbound triggers and goals, and workflows. Tracking needs events:write; reading needs events:read.

From the browser, track events with the Messenger JavaScript API instead — it never exposes an API key.

The event object

One tracked occurrence.

Fields

object string: Always event.
id string: Unique id.
name string: What happened, e.g. invoice-paid.
contactId string: Who did it.
metadata object: Details you sent with the event.
occurredAt timestamp: When it happened.

Example event

{  "object": "event",  "id": "0199c530-3a4b-7c5d-8e6f-7a8b9c0d1e2f",  "name": "invoice-paid",  "contactId": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "metadata": {    "invoice": "INV-4412",    "amount": 149000,    "currency": "eur"  },  "occurredAt": "2026-10-02T15:20:00.000Z"}

Track an event

POST /v1 /events events:write

Records an event for a person. Fires the event.tracked webhook.

Body

name string required: Up to 255 characters; spaces are collapsed.
contactId string: The person, by id. With externalId and email: send exactly one.
externalId string: The person, by your user id.
email string: The person, by email.
metadata object: Up to 20 keys and 8 KB of JSON.
occurredAt timestamp: ISO-8601; defaults to now. Can’t be in the future.

curl -X POST https://api.rabbitblaze.com/v1/events \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "name": "invoice-paid",  "externalId": "usr_48213",  "metadata": {    "invoice": "INV-4412",    "amount": 149000,    "currency": "eur"  }}'

const res = await fetch("https://api.rabbitblaze.com/v1/events", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    name: "invoice-paid",    externalId: "usr_48213",    metadata: {      invoice: "INV-4412",      amount: 149000,      currency: "eur",    },  }),})const data = await res.json()

import osimport requests res = requests.post(    "https://api.rabbitblaze.com/v1/events",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    json={        "name": "invoice-paid",        "externalId": "usr_48213",        "metadata": {            "invoice": "INV-4412",            "amount": 149000,            "currency": "eur",        },    },)res.raise_for_status()data = res.json()

Response · 201 Created

{  "object": "event",  "id": "0199c530-3a4b-7c5d-8e6f-7a8b9c0d1e2f",  "name": "invoice-paid",  "contactId": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "metadata": {    "invoice": "INV-4412",    "amount": 149000,    "currency": "eur"  },  "occurredAt": "2026-10-02T15:20:00.000Z"}

List events

GET /v1 /events events:read

Tracked events, newest first.

Query parameters

name string: Only events with this name.
contactId string: Only this person’s events.
limit integer: Items per page, 1–100. Default 25.
cursor string: The nextCursor of the previous page.

curl https://api.rabbitblaze.com/v1/events?name=invoice-paid&contactId=0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"

const res = await fetch("https://api.rabbitblaze.com/v1/events?name=invoice-paid&contactId=0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f", {  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()

import osimport requests res = requests.get(    "https://api.rabbitblaze.com/v1/events",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    params={        "name": "invoice-paid",        "contactId": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",    },)res.raise_for_status()data = res.json()

Response · 200 OK

{  "items": [    {      "object": "event",      "id": "0199c530-3a4b-7c5d-8e6f-7a8b9c0d1e2f",      "name": "invoice-paid",      "contactId": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",      "metadata": {        "invoice": "INV-4412",        "amount": 149000,        "currency": "eur"      },      "occurredAt": "2026-10-02T15:20:00.000Z"    }  ],  "nextCursor": "WyIyMDI2LTEwLTAyVDE0OjA1OjMxLjAwMFoiLCIwMTk5YzUyMC03ZThmIl0"}