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 (a change that is neither a tracked status transition nor a named sub-event).
`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.
`update.invoice.status.APPROVED` †	A customer invoice is approved. Support-enabled only — not in the dashboard form.

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 (a change that is neither a tracked status transition nor a named sub-event).
`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 document triggers

Trigger	Fires when
`create.carrier_document` †	A document is attached to a carrier invoice. Support-enabled only.
`update.carrier_document` †	A carrier-invoice document is updated or (re)classified. Support-enabled only.
`delete.carrier_document` †	A carrier-invoice document is removed. Support-enabled only.

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.

There are no foundation-entity triggers

Webhooks fire on transactional records — invoices, carrier invoices, payments, documents, exceptions, remittances, approval requests, and BTF batches. They do not fire on the foundation entities you sync in:

Resource	Change events?
Customer	None — no `create.customer` / `update.customer` / `delete.customer`
Carrier	None
Company	None
Address	None
Shipment	None for the shipment record itself. `create.shipment_document` covers its documents, and `update.carrier_invoice.shipment_updated` fires when a carrier invoice is matched to a shipment.

This matters when you’re planning a two-way sync: Upwell will not call you back when one of these records changes. Your TMS remains the system of record for them, and the flow is one-way — you push with POST/PUT, and you poll (GET, or POST /…/search where it exists) if you need to read state back. Subscribe to the transactional triggers above for the events Upwell does originate.

Triggers marked † exist in the dispatcher but are not exposed in the dashboard subscription form for self-service — create/update/delete.carrier_document and update.invoice.status.APPROVED. If you need one of those, contact support@upwell.com. Everything else in the tables above is self-service. For payload shapes and delivery details, see Outbound webhooks.

​Webhook event catalog

​Trigger naming

​Invoice (customer invoice) triggers

​Carrier invoice triggers

​Carrier document triggers

​Carrier-invoice approval request triggers

​Shipment document triggers

​Customer payment triggers

​Breakthrough Fuel triggers

​Exception triggers

​Remittance triggers

​There are no foundation-entity triggers

Webhook event catalog

Trigger naming

Invoice (customer invoice) triggers

Carrier invoice triggers

Carrier document triggers

Carrier-invoice approval request triggers

Shipment document triggers

Customer payment triggers

Breakthrough Fuel triggers

Exception triggers

Remittance triggers

There are no foundation-entity triggers