# Send backend events

Record optional app milestones using authenticated, app-scoped events.

## What you need

A real milestone defined and implemented in your app, the private workspace key and owned HeyCrust app UUID. Shopify does not supply arbitrary in-app activation steps.

## Steps

1. Define the milestone and emit it only when that app action actually succeeds. Examples such as `onboarding_completed` are developer-defined names, not Shopify events automatically present in HeyCrust.
2. POST JSON to `https://heycrust.com/api/events` with `Authorization: Bearer <workspace key>` and `Content-Type: application/json`.
3. Send the single event below or an `events` array of 1–50 events. Use permanent `myshopify.com` domains for app-scoped requests.
4. Reuse `eventId` only for retries of the same content. A changed payload using the same app/event ID can return 409.
5. Check the receipt’s stored/deduped count, `scope` and app-specific result. Configure the Flow’s event name/source/app scope only after observing it.

```json
{
  "appId": "11111111-1111-4111-8111-111111111111",
  "shopDomain": "example.myshopify.com",
  "name": "onboarding_completed",
  "eventId": "example-onboarding-001",
  "occurredAt": "2026-10-07T10:00:00Z",
  "properties": {
    "step": "published",
    "items": 1
  }
}
```

## Expected result

A receipt with `ok`, `stored`, `deduped`, `scope` and result IDs. New integrations should get `scope: "app"`; omitting appId uses the legacy unscoped path and cannot establish the intended app evidence.

## What this proves

An authenticated backend event records what your app reported for a merchant and app. It does not create a Shopify collection, affiliate commission or independent verification of your milestone. Missing/stale tracking stays unknown. Use [Browser tracking](/docs/developers/browser-tracking) for optional analytics-grade observations and [Data sources](/docs/app-owners/source-verification) for their boundaries.

## Troubleshooting

Event names allow letters, digits, underscore, dot and hyphen, up to 64 characters; stored names are lowercase. Properties allow at most 20 keys (64 characters), with string values up to 500 characters, numbers, booleans or null. occurredAt must be ISO datetime; eventId is 1–128 characters. Future times are clamped to receipt time.