> ## Documentation Index
> Fetch the complete documentation index at: https://photonhealth.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook events

> Every order and prescription event, with its data.

Every event has the [same envelope](/docs/network/webhooks#the-request). This page lists each `type` and its `data`.

| Event | When |
| - | - |
| `photon:order:created` | An order was sent |
| `photon:order:placed` | The order was sent to a pharmacy |
| `photon:order:fulfillment` | The pharmacy made progress: received, ready, filling, shipped and so on |
| `photon:order:rerouted` | The order moved to a different pharmacy |
| `photon:order:completed` | Picked up or delivered |
| `photon:order:canceled` | Canceled |
| `photon:order:error` | Something went wrong that needs attention |
| `photon:prescription:created` | A draft became an active prescription |
| `photon:prescription:depleted` | Every fill the prescription allows is on an order |
| `photon:prescription:active` | A depleted prescription has fills available again |
| `photon:prescription:canceled` | The prescription was canceled |

Every event's `data` includes the record's `id`, its `externalId` when one was set, and the `patient` as `{ id, externalId }`.

## Order events

### photon:order:created

An order was sent. Each prescription on it becomes a fill.

```json theme={"dark"}
"data": {
  "id": "ord_01M3WT5GK51DBRH7ZKBKBV9QWK",
  "externalId": "1234",
  "pharmacyId": "phr_01GA9HPW4SJGXGZSYA8FNCPM8C",
  "patient": { "id": "pat_01M3WQQHRB1T0K1469KD18BAWX", "externalId": "1234" },
  "fills": [
    { "id": "fil_01G8AHAFNSH1PJMGWECX3BYEP2", "prescription": { "id": "rx_01M3WT4NERS2YVQRF6YTWR4A6C", "externalId": "1234" } }
  ]
}
```

`pharmacyId` is set when the pharmacy was chosen before sending, and is `null` while the patient is still choosing.

### photon:order:placed

The order was sent to a pharmacy. If it's rerouted, you get this event again for the new pharmacy.

```json theme={"dark"}
"data": {
  "id": "ord_01M3WT5GK51DBRH7ZKBKBV9QWK",
  "externalId": "1234",
  "patient": { "id": "pat_01M3WQQHRB1T0K1469KD18BAWX", "externalId": "1234" },
  "pharmacy": {
    "id": "phr_01J6APWHGNFJCE74SB031VYABC",
    "name": "Example Pharmacy",
    "phone": "+15025550123",
    "address": { "street1": "4343 Test Street", "street2": null, "city": "Georgetown", "state": "KY", "postalCode": "40004" }
  }
}
```

### photon:order:fulfillment

The pharmacy made progress. You get one event for each step.

```json theme={"dark"}
"data": {
  "id": "ord_01M3WT5GK51DBRH7ZKBKBV9QWK",
  "externalId": "1234",
  "fulfillment": { "type": "MAIL_ORDER", "state": "SHIPPED", "carrier": "USPS", "trackingNumber": "1LS729104296564" },
  "patient": { "id": "pat_01M3WQQHRB1T0K1469KD18BAWX", "externalId": "1234" }
}
```

| `fulfillment.type` | `fulfillment.state`, in order |
| - | - |
| `PICK_UP` | `RECEIVED` (the pharmacy confirmed it can fill the order), `READY` (waiting for pickup), `PICKED_UP` |
| `MAIL_ORDER` (delivered to the patient) | `FILLING`, `SHIPPED`, `DELIVERED` |

`carrier` and `trackingNumber` are included when the pharmacy provides them.

### photon:order:rerouted

The order moved to a different pharmacy, usually because the patient chose another one. `pharmacy` is the new pharmacy, with the same shape as in `photon:order:placed`.

### photon:order:completed

Picked up or delivered. `data` has only `id`, `externalId` and `patient`.

### photon:order:canceled

Canceled. `data` has only `id`, `externalId` and `patient`.

### photon:order:error

Something went wrong with the order that needs attention.

```json theme={"dark"}
"data": {
  "id": "ord_01M3WT5GK51DBRH7ZKBKBV9QWK",
  "externalId": "1234",
  "reason": "…",
  "patient": { "id": "pat_01M3WQQHRB1T0K1469KD18BAWX", "externalId": "1234" }
}
```

`reason` explains what went wrong, for a person to read.

## Prescription events

### photon:prescription:created

A draft became an active prescription. Drafts themselves send no events.

```json theme={"dark"}
"data": {
  "id": "rx_01M3WT4NERS2YVQRF6YTWR4A6C",
  "externalId": "1234",
  "treatmentId": "med_01G7T2NB6",
  "prescriberId": "usr_wUofzqEvcA2JCwJ4",
  "instructions": "Take once daily",
  "notes": "",
  "dispenseQuantity": 30,
  "dispenseUnit": "Tablet",
  "dispenseAsWritten": true,
  "fillsAllowed": 3,
  "refillsAllowed": 2,
  "daysSupply": 30,
  "effectiveDate": "2026-10-08",
  "expirationDate": "2027-10-08",
  "patient": { "id": "pat_01M3WQQHRB1T0K1469KD18BAWX", "externalId": "1234" }
}
```

| Field | Description |
| - | - |
| `treatmentId` | The drug's catalog id |
| `prescriberId` | The prescriber who signed it |
| `fillsAllowed` | How many times it can be filled in total. `refillsAllowed` is one less. |
| `effectiveDate`, `expirationDate` | When the prescription is valid |

### photon:prescription:depleted

Every fill the prescription allows is now on an order, so it can't be ordered again. This doesn't mean the medication has been picked up or has run out. A one-fill prescription is depleted as soon as its order is sent. `data` has only `id`, `externalId` and `patient`.

### photon:prescription:active

A depleted prescription has fills available again, for example because an order with one of its fills was canceled. `data` has only `id`, `externalId` and `patient`.

### photon:prescription:canceled

The prescription was canceled and can't be filled. `data` has only `id`, `externalId` and `patient`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.