Skip to main content
Configure webhook destinations so Subtotal knows where to send events. You can do this in the Subtotal Dashboard, with the webhooks API, or by asking an AI assistant through Subtotal: For Brands.

Create a webhook destination

1

Sign in to the Subtotal Dashboard

Sign in to the Subtotal Dashboard and select Webhooks from the side menu.subtotal webhooks
2

Add a webhook destination

Click Add Webhook Destination and specify a name and URL.subtotal webhook destination
You will receive a signing secret for the destination. Store this secret securely and use it to verify webhook signatures for every request. Keep your signing secret private.
3

Configure events

Select the Configure option on your new webhook destination. Enable the events that you’d like this destination to receive.subtotal configure webhook

Wait for the purchase to complete

Open Configure for a webhook destination. Under its purchase.created subscription, turn on Wait for the purchase to complete. connection.activated sends purchases after a reconnect and uses Wait for the purchase to complete from the same destination’s purchase.created subscription; see Event types. Wait for the purchase to complete is off by default. It applies separately to each purchase event or earning action. The event's other conditions, such as retailers and purchase dates, also apply. With the option on: If status is null, purchases from Amazon, Walmart, and Target wait because these retailers report status. Purchases from every other retailer send at share time. If a waiting purchase remains open or has no status, Subtotal sends it about 31 days after the purchase date. A purchase already past that deadline sends at share time. A delivery after the wait counts once, the same as a normal Purchase shared delivery. Waiting does not create an extra billable event. Simulated purchases from the Event Simulator always send at share time. With the option on, the event sends each purchase at most once, even when the purchase is shared again after a reconnect. With the option off, the event sends each qualifying purchase when it is shared.

Pause or turn on a webhook

The Active switch in the Configure dialog turns deliveries on and off. A paused webhook shows a Paused badge on the Webhooks page and receives no events until it’s turned back on. Turning a webhook on is the step that starts sending your data to its URL, so check that the URL shown is yours first.

With the API

The webhooks API lists, creates, updates and deletes webhooks with your API key:
A new webhook starts paused unless the request sets is_active to true. The response includes the signing secret, which is shown only once. Use event names from Event types; an unknown name returns a 422 that lists the valid names.

With Subtotal: For Brands

Ask an AI assistant connected through Subtotal: For Brands to set up a webhook, for example “Send new purchases to https://hooks.example.com/subtotal”. The assistant uses the webhook tools and gives you the signing secret once.
A webhook the connector creates starts paused unless you ask the assistant to make it live. Turn it on later by asking the assistant, or from the Webhooks page of the dashboard as described in Pause or turn on a webhook. Check that the URL is yours before a webhook goes live: from then on it receives your data.

Requirements

  • Your endpoint must be HTTPS on port 443, with no username or password in the URL, on a host that resolves only to public IP addresses. See URL requirements.
  • Your endpoint must respond with a 2xx status within 10 seconds. Failed deliveries are retried for up to about 17.5 hours; see Delivery and retries.
  • Deduplicate delivery retries on id. For repeat purchases, use payload.purchase.purchase_id with payload.connection.connection_id; see Event types.
  • Implement signature verification to ensure requests are from Subtotal.