Overview
Webhooks let you subscribe to Subtotal system events and receive real-time HTTP requests when those events occur. Use webhooks to keep your systems in sync with connection and purchase activity.Properties included with every event
These properties are included with each webhook request:
The same purchase can arrive in more than one
purchase.created event: once for each active connection on the retail account. It can arrive again each time a connection that lost access signs in. Deduplicate purchases on payload.purchase.purchase_id with payload.connection.connection_id.
Below are all supported event types and their corresponding payload structures.
connection.activated
Sent on every account activation: first links, reconnects, and routine sign-ins.
Example
connection.activated event
connection.unauthenticated
Sent when a connection moves fromactive to unauthenticated because the customer must sign in again, for example after a retailer password change.
Example
connection.unauthenticated event
connection.disconnected
Sent when the consumer, your app through the API, or an assistant through thedisconnect_connection tool in Subtotal: For Brands disconnects the connection.
Example
connection.disconnected event
connection.profile.created
Sent the first time Subtotal captures a consumer’s profile for a connection — their identity details from the linked retailer account, together with purchase metrics scoped to your brands.Unlike the other
connection.* events, the profile payload is flat: its fields sit directly under payload, not under payload.connection.Profile events are only delivered for active connections. While a connection is
unauthenticated or disconnected you will not receive profile events for it; if the profile changed in the meantime, the connection receives a single catch-up event when it is re-linked (alongside connection.activated).
Example
connection.profile.created event
connection.profile.updated
Sent when the collected identity changes: name, email, mobile, postal code or retailer account creation date. New purchases alone do not send it. Each profile event carries the latest purchase metrics. The payload has the same shape asconnection.profile.created. This event is only delivered while the connection is active. Changes collected while a connection is unauthenticated or disconnected arrive as one event when the connection signs in again.
Example
connection.profile.updated event
purchase.created
Thepurchase.created event is sent when a purchase from a customer’s connected retailer account is shared with your brand. This may differ from when Subtotal first collected the purchase.
The dashboard calls this trigger Purchase shared.
status is the purchase status when the event is sent. A later status change sends no event; read it from GET /purchases/.
When an account first connects, the destination’s purchase.created subscription receives the account’s history. When a connection signs in after it lost access, the destination’s connection.activated subscription also sends purchase.created for purchases collected since that loss. Subscribe to both to receive every shared purchase.
Purchase status
status is the purchase status the retailer last showed. The value is a string, or null when unknown.
The possible string values are:
pendingshippedready_for_pickupcompletedcancelled
null.
completed and cancelled are final. Once a purchase reaches either status, its status does not change again.
Example purchase.created event