Event types

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:

Key	Type	Description
type	string	The webhook event type
id	string	Identifier for the webhook
payload	string	The payload of the webhook

Below are all supported event types and their corresponding payload structures.

connection.activated

Connections are activated when a customer successfully links their account.

Key	Type	Description
payload.connection.connection_id	string	Identifier for the connection
payload.connection.customer_id	string	Identifier for the associated customer
payload.connection.retailer_id	string	Identifier for the retailer in the connection
payload.connection.email	string	Email address of the associated customer
payload.connection.mobile	string	Mobile phone number of the associated customer
payload.connection.status	string	Current status of the connection

Example connection.activated event

{
  "type": "connection.activated",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection": {
      "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
      "customer_id": "01K8BPF2393S9VB6JQT99GK447",
      "retailer_id": "target",
      "email": null,
      "mobile": null,
      "status": "active"
    }
  }
}

connection.unauthenticated

Connections move from activated to unauthenticated when a customer needs to re-authenticate their account. For example, when a customer changes their password with the retailer.

Key	Type	Description
payload.connection.connection_id	string	Identifier for the connection
payload.connection.customer_id	string	Identifier for the associated customer
payload.connection.retailer_id	string	Identifier for the retailer in the connection
payload.connection.email	string	Email address of the associated customer
payload.connection.mobile	string	Mobile phone number of the associated customer
payload.connection.status	string	Current status of the connection

Example connection.unauthenticated event

{
  "type": "connection.unauthenticated",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection": {
      "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
      "customer_id": "01K8BPF2393S9VB6JQT99GK447",
      "retailer_id": "target",
      "email": null,
      "mobile": null,
      "status": "unauthenticated"
    }
  }
}

connection.disconnected

Connections move to disconnected status when a customer disconnects their account.

Key	Type	Description
payload.connection.connection_id	string	Identifier for the connection
payload.connection.customer_id	string	Identifier for the associated customer
payload.connection.retailer_id	string	Identifier for the retailer in the connection
payload.connection.email	string	Email address of the associated customer
payload.connection.mobile	string	Mobile phone number of the associated customer
payload.connection.status	string	Current status of the connection

Example connection.disconnected event

{
  "type": "connection.disconnected",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection": {
      "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
      "customer_id": "01K8BPF2393S9VB6JQT99GK447",
      "retailer_id": "target",
      "email": null,
      "mobile": null,
      "status": "disconnected"
    }
  }
}

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

Key	Type	Description
payload.connection_id	string	Identifier for the connection
payload.first_name	string	Consumer’s first name (`null` if unavailable)
payload.last_name	string	Consumer’s last name (`null` if unavailable)
payload.email	string	Consumer’s email address (`null` if unavailable)
payload.mobile	string	Consumer’s mobile phone number (`null` if unavailable)
payload.postal_code	string	Consumer’s postal code (`null` if unavailable)
payload.account_created_date	string	When the consumer’s retailer account was created (ISO 8601; `null` if unknown)
payload.total_purchases	number	All-time number of purchases on the connected account
payload.last_purchase_date	string	Date of the most recent purchase (ISO 8601; `null` if none)
payload.brand_purchases	number	Number of those purchases you are authorized to see (matching your brands)
payload.last_brand_purchase_date	string	Date of the most recent brand purchase (ISO 8601; `null` if none)
payload.brand_purchase_rate	number	`brand_purchases` ÷ `total_purchases`, from `0.0` to `1.0`

Example connection.profile.created event

{
  "type": "connection.profile.created",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
    "first_name": "Jessica",
    "last_name": "Smith",
    "email": "[email protected]",
    "mobile": "+123456789",
    "postal_code": "84101",
    "account_created_date": "2024-03-12T00:00:00Z",
    "total_purchases": 42,
    "last_purchase_date": "2026-01-15T14:30:00Z",
    "brand_purchases": 7,
    "last_brand_purchase_date": "2026-01-14T09:45:00Z",
    "brand_purchase_rate": 0.17
  }
}

connection.profile.updated

Sent when a previously captured profile changes — for example an updated email or postal code, or when new purchases shift the brand-purchase metrics. The payload is identical in shape to connection.profile.created. Like connection.profile.created, this event is only delivered while the connection is active; changes that happen while a connection is unauthenticated or disconnected arrive as one catch-up event on re-link.

Key	Type	Description
payload.connection_id	string	Identifier for the connection
payload.first_name	string	Consumer’s first name (`null` if unavailable)
payload.last_name	string	Consumer’s last name (`null` if unavailable)
payload.email	string	Consumer’s email address (`null` if unavailable)
payload.mobile	string	Consumer’s mobile phone number (`null` if unavailable)
payload.postal_code	string	Consumer’s postal code (`null` if unavailable)
payload.account_created_date	string	When the consumer’s retailer account was created (ISO 8601; `null` if unknown)
payload.total_purchases	number	All-time number of purchases on the connected account
payload.last_purchase_date	string	Date of the most recent purchase (ISO 8601; `null` if none)
payload.brand_purchases	number	Number of those purchases you are authorized to see (matching your brands)
payload.last_brand_purchase_date	string	Date of the most recent brand purchase (ISO 8601; `null` if none)
payload.brand_purchase_rate	number	`brand_purchases` ÷ `total_purchases`, from `0.0` to `1.0`

Example connection.profile.updated event

{
  "type": "connection.profile.updated",
  "id": "01KFJSR44CPH867805V8GJ9VCY",
  "payload": {
    "connection_id": "01K8BPF23CCZ2FK50STB8EGWAV",
    "first_name": "Jessica",
    "last_name": "Smith",
    "email": "[email protected]",
    "mobile": "+123456789",
    "postal_code": "84101",
    "account_created_date": "2024-03-12T00:00:00Z",
    "total_purchases": 43,
    "last_purchase_date": "2026-02-02T18:05:00Z",
    "brand_purchases": 8,
    "last_brand_purchase_date": "2026-02-02T18:05:00Z",
    "brand_purchase_rate": 0.19
  }
}

purchase.created

The purchase.created event is sent when a new purchase is received from a customer’s connected retailer account. We recommend using this event when you need to process customer purchases for your use case.

Key	Type	Description
payload.connection.connection_id	string	Identifier for the connection
payload.connection.customer_id	string	Identifier for the associated customer
payload.connection.retailer_id	string	Identifier for retailer in the connection
payload.connection.email	string	Email address of the associated customer
payload.connection.mobile	string	Mobile phone number of the associated customer
payload.connection.status	string	Current status of the connection
payload.purchase.purchase_id	string	Identifier for the purchase
payload.purchase.date	string	Date of the purchase (ISO 8601)
payload.purchase.item_count	number	The number of items in the purchase
payload.purchase.subtotal	number	The subtotal of the purchase
payload.purchase.tax	number	The sales tax that was paid
payload.purchase.total	number	Total amount of the purchase
payload.purchase.items[].item_id	string	Identifier for the item
payload.purchase.items[].price	number	Price of the item
payload.purchase.items[].quantity	number	Quantity as shown on the receipt; items sold by weight show 1
payload.purchase.items[].unit_quantity	number	Actual quantity purchased; fractional for items sold by weight, so `price × unit_quantity` is the amount spent
payload.purchase.items[].product.product_id	string	Identifier for the product
payload.purchase.items[].product.name	string	The name of the product
payload.purchase.items[].product.description	string	Description of the item
payload.purchase.items[].product.upc	string	Universal identifier for the product (UPC)
payload.purchase.items[].product.brand	string	The brand associated with the product

Example purchase.created event

{
  "id": "01J51S0JYV6N7K1030CV1ZBDOW",
  "type": "purchase.created",
  "payload": {
    "connection": {
      "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
      "customer_id": "01K8HDK6Y9FXM7ES4NJSHZDEKF",
      "retailer_id": "walmart",
      "email": "[email protected]",
      "mobile": "+123456789",
      "status": "active"
    },
    "purchase": {
      "purchase_id": "01J51S0JYV6N7K1030CV1ZKSJH",
      "date": "2025-10-08T14:23:00Z",
      "total": 47.85,
      "subtotal": 43.50,
      "tax": 4.35,
      "items": [
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": 5.99,
          "quantity": 2,
          "unit_quantity": 2,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA", 
            "name": "Sparkling Water 12pk",
            "description": "Sparkling Water 12-Pack - 12 fl oz bottles",
            "upc": "001234567890",
            "brand": "la-croix"
          }
        },
        {
          "item_id": "01K3KS9Q4522E3HG444E4XH1R0",
          "price": 12.99,
          "quantity": 1,
          "unit_quantity": 1,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Trail Mix",
            "description": "Trail Mix Family Size", 
            "upc": "009876543210",
            "brand": "harvest-one"
          }
        },
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": 8.50,
          "quantity": 1,
          "unit_quantity": 2.18,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Organic Cherries",
            "description": "Organic Cherries, sold by the pound",
            "upc": "011122233344",
            "brand": "harvest-one"
          }
        }
      ]
    }
  }
}

Documentation

Platform

Integrations

Guides

Overview

Properties included with every event

connection.activated

connection.unauthenticated

connection.disconnected

connection.profile.created

connection.profile.updated

purchase.created

​Overview

​Properties included with every event

​connection.activated

​connection.unauthenticated

​connection.disconnected

​connection.profile.created

​connection.profile.updated

​purchase.created

Overview

Properties included with every event

connection.activated

connection.unauthenticated

connection.disconnected

connection.profile.created

connection.profile.updated

purchase.created