# Webhook payloads
URL: https://docs.awellhealth.com/api-reference/guides/webhook-payloads

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).



This page shows the payload Awell posts to your endpoint for each event. Which events exist and when they
fire is in the [webhook event catalog](/docs/automate-with-events/webhook-event-catalog); building the
endpoint is in [Receive webhook events](/docs/automate-with-events/receive-webhook-events).

**Payloads carry identifiers, not clinical detail.** Fetch what you need through the API using them.

## Every payload [#every-payload]

All payloads include an `event_type` identifying which event fired, and an `id`. Always **switch** on
`event_type` rather than inferring the event from which fields are present.

## Activity events [#activity-events]

`activity.created` · `activity.completed` · `activity.updated` · `activity.expired` ·
`activity.failed` · `activity.deleted`

**These share one payload shape**, so handle them with one parser and branch on `event_type`.

```json
{
  "event_type": "<EVENT_TYPE>",
  "activity": {
    "id": "<ACTIVITY_ID>",
    "stream_id": "<PATHWAY_ID>",
    "date": "<CREATION_DATE>",
    "action": "<ACTION>",
    "status": "<STATUS>",
    "subject": { "type": "awell", "name": "Awell" },
    "object": { "id": "<OBJECT_ID>", "type": "<OBJECT_TYPE>", "name": "<OBJECT_NAME>" },
    "indirect_object": { "id": "<ID>", "type": "<TYPE>", "name": "<NAME>" },
    "context": { "instance_id": "<ID>", "pathway_id": "<ID>", "track_id": "<ID>", "step_id": "<ID>", "action_id": "<ID>" },
    "sub_activities": [],
    "label": { "id": "<ID>", "text": "<TEXT>", "color": "<COLOR>" },
    "track": { "id": "<ID>", "title": "<TITLE>" }
  }
}
```

The `context` object locates the activity in the care flow's structure, and `object` says what the
activity is about; both matter when deciding whether to act on an event.

## Care flow events [#care-flow-events]

`pathway.started` · `pathway.completed` · `pathway.stopped` · `pathway.deleted`

**Note the event name.** These use `pathway`, not `care_flow`. The product renamed *pathway*
to *care flow*; the wire format did not follow, which is also why the payload wrapper below is
`pathway`. Subscribe to the names above — they are what the platform sends and what the event
picker in Studio lists.

```json
{
  "event_type": "<EVENT_TYPE>",
  "pathway": {
    "id": "<PATHWAY_ID>",
    "pathway_definition_id": "<DEFINITION_ID>",
    "pathway_title": "<TITLE>",
    "patient_id": "<PATIENT_ID>",
    "patient_identifiers": [{ "system": "<SYSTEM>", "value": "<VALUE>" }],
    "start_date": "<DATE>",
    "tenant_id": "<TENANT_ID>"
  }
}
```

`patient_identifiers` lets you match the care flow to a patient in your own system without storing
Awell IDs.

## Patient events [#patient-events]

`patient.created` · `patient.updated` · `patient.deleted`

```json
{
  "event_type": "<EVENT_TYPE>",
  "patient": {
    "id": "<PATIENT_ID>",
    "patient_code": "<YOUR_CODE>",
    "identifier": [{ "system": "<SYSTEM>", "value": "<VALUE>" }],
    "profile": {
      "first_name": "<NAME>", "last_name": "<NAME>", "birth_date": "<ISO8601>",
      "sex": "<SEX>", "email": "<EMAIL>", "phone": "<E164>", "mobile_phone": "<E164>",
      "preferred_language": "<LANG>", "national_registry_number": "<NRN>",
      "address": { "street": "<S>", "city": "<C>", "zip": "<Z>", "state": "<S>", "country": "<C>" }
    }
  }
}
```

Patient payloads are the one exception to identifiers-not-detail: they carry profile fields, because the
event *is* about the profile. Treat them as PHI accordingly.

## Track, session, form and note events [#track-session-form-and-note-events]

`track.started` · `track.completed` · `track.stopped` · `session.started` · `session.completed` ·
`session.expired` · `form.submitted` · `data_point.collected` · `clinical_note.created` ·
`reminder.created`

Each carries `event_type` plus an object naming what it concerns, following the same identifier-led shape
as above.

## Handling advice [#handling-advice]

* **Switch on `event_type`.** Never infer the event from field presence.
* **Expect unknown event types.** New events get added, so an unrecognized type should be ignored, not
  fatal.
* **Order isn't guaranteed and delivery can repeat.** See
  [Webhooks and events](/docs/automate-with-events/webhooks-and-events).