# Webhook events

You choose which events each endpoint receives. Every event has the same payload shape (see [Webhooks](https://docs.rephut.com/developers/webhooks)): `data.id` is the id of what changed and `data.status` its status after the change.

### `order.status_changed`

Shown in the portal as **Order status changed**. An order was created or its status changed, for example to RESERVED, WEIGHED, SHIPPED or CANCELLED.

- **Sent when:** An order is created (its first status) and every time its status changes afterwards, whether the change came from the API, the portal, a connected store or our team.
- **`data.id`:** Order id. Fetch it with GET /v1/orders/{id}.
- **`data.status`:** one of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`.

### `order.awaiting_payment`

Shown in the portal as **Order needs payment to ship**. Your available balance didn't cover the shipping and handling fee when the parcel was weighed. The order waits for a top-up; GET the order for the amount due.

- **Sent when:** Our warehouse weighed the parcel and your available balance didn't cover the shipping and handling fee: sent once per unpaid round, at the same time as the portal notification. A re-weigh in the same round that changes the amount due sends nothing; GET the order for the current amount.
- **`data.id`:** Order id. GET /v1/orders/{id} shows the amount due.
- **`data.status`:** Always `RESERVED`.

### `purchase_order.status_changed`

Shown in the portal as **Purchase order status changed**. A purchase order was created or its status changed.

- **Sent when:** A purchase order is created (status `AWAITING_PAYMENT`) and every time its status changes afterwards.
- **`data.id`:** Purchase order id. Fetch it with GET /v1/purchase-orders/{id}.
- **`data.status`:** one of `AWAITING_PAYMENT`, `DEPOSIT_PAID`, `PAID`, `PURCHASING`, `ORDERED`, `IN_TRANSIT`, `PARTIALLY_ARRIVED`, `ARRIVED`, `STORED`, `COMPLETED`, `CANCELLED`.

### `shipment.status_changed`

Shown in the portal as **Shipment status changed**. A shipment was created by you in the portal, sent to you for confirmation, or changed status.

- **Sent when:** A shipment you can see is created or changes status: one you asked for, or one we prepared and sent you (we don't send events for our drafts).
- **`data.id`:** Shipment id. Fetch it with GET /v1/shipments/{id}.
- **`data.status`:** one of `DRAFT`, `PENDING_CONFIRMATION`, `AWAITING_PAYMENT`, `PAID`, `SHIPPED`, `CANCELLED`.

### `shipment.tracking_updated`

Shown in the portal as **Shipment tracking numbers added**. Tracking numbers were added to a shipment. GET the shipment to read them.

- **Sent when:** Tracking numbers are added to a shipment (today this happens when it ships).
- **`data.id`:** Shipment id. GET /v1/shipments/{id} lists the tracking numbers.
- **`data.status`:** Always `SHIPPED`.

### `quote.created`

Shown in the portal as **New quote ready**. We sent you a quote. A new version of a quote has a new id.

- **Sent when:** We send you a quote, and again for each new version (a new version has a new id). The status is always `AWAITING`.
- **`data.id`:** Quote id. Fetch it with GET /v1/quotes/{id}.
- **`data.status`:** Always `AWAITING`.

### `wallet.top_up_approved`

Shown in the portal as **Top-up approved**. A top-up was approved and credited to your wallet.

- **Sent when:** We approve a pending top-up, or record a top-up for you directly. The status is always `CONFIRMED`.
- **`data.id`:** Top-up id, as listed by GET /v1/wallet/top-ups.
- **`data.status`:** Always `CONFIRMED`.

## Test events

`webhook.test` is sent only when you click **Send test event** in the portal. Its `data.id` is the endpoint's id and `data.status` is `TEST`. You can't subscribe to it. See [Webhook delivery and retries](https://docs.rephut.com/developers/webhooks/delivery#test-events).

## Good to know

- Events cover changes from every source: the API, the portal, connected stores and our team.
- A newly created resource and a status change look the same: the payload doesn't say what the status was before.
- If something changes and changes back within one update, no event is sent.
- Events are recorded only while API access is on for your account, for endpoints that are on and subscribed to that event.

No event is sent for:

- Changing an order's tracking number after it shipped.
- Accepting or declining a quote.
- Rejecting a top-up.
- Voiding an approved top-up.
- A quote expiring or becoming `UPDATING` or `SUPERSEDED`: these are worked out when you read the quote, not written as changes.