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

# Webhook event catalog

> Every webhook trigger you can subscribe to in the Upwell dashboard, grouped by resource — the companion reference to the outbound webhooks guide.

# Webhook event catalog

This is the reference list of the webhook triggers you can **subscribe to in the Upwell dashboard**. For **how** webhooks work — subscribing, the delivery envelope, auth, retries, and a receiver example — see [Outbound webhooks](/api-guides/webhooks).

## Trigger naming

Triggers are dot-delimited strings. Most take one of these shapes:

```
{action}.{resource}
{action}.{resource}.status.{STATUS}
{action}.{resource}.{event}
```

* `action` is `create`, `update`, or `delete`.
* `.status.{STATUS}` fires only on a specific status transition.
* `.{event}` is a named sub-event rather than a status — e.g. `update.carrier_invoice.shipment_updated`, which fires when the invoice is matched to a shipment.

Each change produces **exactly one** trigger — the most specific one that applies — and a subscription receives an event **only if it subscribed to that exact trigger string**. A generic `update.{resource}` is *not* also delivered alongside a `.status.{STATUS}` or `.{event}` trigger; `update.{resource}` fires for a change that is neither a tracked status transition nor a named sub-event. So to catch more than one case, subscribe to each trigger you care about. Match the string verbatim, including case — most status suffixes are upper-case (`APPROVED`, `SENT`), but the remittance ones are lower-case. The tables below are the source of truth.

## Invoice (customer invoice) triggers

| Trigger                                  | Fires when                                 |
| ---------------------------------------- | ------------------------------------------ |
| `create.invoice`                         | A new invoice record is created.           |
| `update.invoice`                         | An invoice record is updated.              |
| `delete.invoice`                         | An invoice record is deleted.              |
| `update.invoice.status.SENT`             | A customer invoice is sent.                |
| `update.invoice.status.PORTAL_EXCEPTION` | A customer invoice has a portal exception. |

## Carrier invoice triggers

| Trigger                                                                               | Fires when                                                                     |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `create.carrier_invoice`                                                              | A new carrier invoice record is created.                                       |
| `update.carrier_invoice`                                                              | A carrier invoice record is updated.                                           |
| `delete.carrier_invoice`                                                              | A carrier invoice record is deleted.                                           |
| `create.carrier_invoice.shipment_updated` / `update.carrier_invoice.shipment_updated` | The carrier invoice was matched/linked to a shipment (fires during ingestion). |
| `update.carrier_invoice.status.APPROVED`                                              | A carrier invoice has been approved (review lifecycle).                        |
| `update.carrier_invoice.status.EXCEPTION`                                             | A carrier invoice hit an exception status (review lifecycle).                  |

<Note>
  To distinguish *ingestion done* from the later *review lifecycle*, see the guidance in [Knowing when a carrier invoice is processed](/api-guides/carrier-invoice-status).
</Note>

## Carrier-invoice approval request triggers

| Trigger                                   | Fires when                                                                                                                          |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `create.carrier_invoice_approval_request` | An approval request is opened for a carrier invoice. See [Responding to an approval request](/api-guides/carrier-invoice-approval). |

## Shipment document triggers

| Trigger                    | Fires when                                 |
| -------------------------- | ------------------------------------------ |
| `create.shipment_document` | A new shipment document record is created. |
| `update.shipment_document` | A shipment document record is updated.     |
| `delete.shipment_document` | A shipment document record is deleted.     |

## Customer payment triggers

| Trigger                   | Fires when                                |
| ------------------------- | ----------------------------------------- |
| `create.customer_payment` | A new customer payment record is created. |
| `update.customer_payment` | A customer payment record is updated.     |
| `delete.customer_payment` | A customer payment record is deleted.     |

## Breakthrough Fuel triggers

| Trigger            | Fires when                                |
| ------------------ | ----------------------------------------- |
| `create.btf_batch` | A new Breakthrough Fuel batch is created. |

## Exception triggers

| Trigger                            | Fires when                 |
| ---------------------------------- | -------------------------- |
| `create.exception`                 | A new exception is raised. |
| `update.exception.status.RESOLVED` | An exception is resolved.  |

## Remittance triggers

| Trigger                               | Fires when                             |
| ------------------------------------- | -------------------------------------- |
| `create.remittance`                   | A new remittance is created.           |
| `update.remittance`                   | A remittance is updated.               |
| `delete.remittance`                   | A remittance is deleted.               |
| `update.remittance.status.pending`    | A remittance moved to `pending`.       |
| `update.remittance.status.succeeded`  | A remittance moved to `succeeded`.     |
| `update.remittance.status.sync_error` | A remittance hit a sync error.         |
| `create.remittance_line_item`         | A new remittance line item is created. |
| `update.remittance_line_item`         | A remittance line item is updated.     |
| `delete.remittance_line_item`         | A remittance line item is deleted.     |

<Note>
  This catalog lists the triggers offered in the dashboard subscription form. Upwell's dispatcher can emit some additional internal events that aren't exposed there for subscription — if you need an event you don't see here, check with support. For payload shapes and delivery details, see [Outbound webhooks](/api-guides/webhooks).
</Note>