Skip to main content

​
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:
KeyTypeDescription
typestringThe webhook event type
idstringIdentifier for the webhook
payloadstringThe 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.
KeyTypeDescription
payload.connection.connection_idstringIdentifier for the connection
payload.connection.customer_idstringIdentifier for the associated customer
payload.connection.retailer_idstringIdentifier for the retailer in the connection
payload.connection.emailstringEmail address of the associated customer
payload.connection.mobilestringMobile phone number of the associated customer
payload.connection.statusstringCurrent 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.
KeyTypeDescription
payload.connection.connection_idstringIdentifier for the connection
payload.connection.customer_idstringIdentifier for the associated customer
payload.connection.retailer_idstringIdentifier for the retailer in the connection
payload.connection.emailstringEmail address of the associated customer
payload.connection.mobilestringMobile phone number of the associated customer
payload.connection.statusstringCurrent 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.
KeyTypeDescription
payload.connection.connection_idstringIdentifier for the connection
payload.connection.customer_idstringIdentifier for the associated customer
payload.connection.retailer_idstringIdentifier for the retailer in the connection
payload.connection.emailstringEmail address of the associated customer
payload.connection.mobilestringMobile phone number of the associated customer
payload.connection.statusstringCurrent 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"
    }
  }
}

​
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.
KeyTypeDescription
payload.connection.connection_idstringIdentifier for the connection
payload.connection.customer_idstringIdentifier for the associated customer
payload.connection.retailer_idstringIdentifier for retailer in the connection
payload.connection.emailstringEmail address of the associated customer
payload.connection.mobilestringMobile phone number of the associated customer
payload.connection.statusstringCurrent status of the connection
payload.purchase.purchase_idstringIdentifier for the purchase
payload.purchase.datestringDate of the purchase (ISO 8601)
payload.purchase.item_countnumberThe number of items in the purchase
payload.purchase.subtotalnumberThe subtotal of the purchase
payload.purchase.taxnumberThe sales tax that was paid
payload.purchase.totalnumberTotal amount of the purchase
payload.purchase.items[].item_idstringIdentifier for the item
payload.purchase.items[].pricenumberPrice of the item
payload.purchase.items[].quantitynumberThe quantity purchased
payload.purchase.items[].product.product_idstringIdentifier for the product
payload.purchase.items[].product.namestringThe name of the product
payload.purchase.items[].product.descriptionstringDescription of the item
payload.purchase.items[].product.upcstringUniversal identifier for the product (UPC)
payload.purchase.items[].product.brandstringThe 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": "jessica@acme.com",
      "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,
          "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,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Trail Mix",
            "description": "Trail Mix Family Size", 
            "upc": "009876543210",
            "brand": "harvest-one"
          }
        },
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": 18.53,
          "quantity": 1,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Face Cream",
            "description": "Moisturizing Face Cream",
            "upc": "011122233344",
            "brand": "glowww"
          }
        }
      ]
    }
  }
}