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.

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).

To distinguish ingestion done from the later review lifecycle, see the guidance in Knowing when a carrier invoice is processed.

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.

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.

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.

​Webhook event catalog

​Trigger naming

​Invoice (customer invoice) triggers

​Carrier invoice triggers

​Carrier-invoice approval request triggers

​Shipment document triggers

​Customer payment triggers

​Breakthrough Fuel triggers

​Exception triggers

​Remittance triggers

Webhook event catalog

Trigger naming

Invoice (customer invoice) triggers

Carrier invoice triggers

Carrier-invoice approval request triggers

Shipment document triggers

Customer payment triggers

Breakthrough Fuel triggers

Exception triggers

Remittance triggers