Guide · HubSpot
HubSpot webhook: every conversion attributed
HubSpot knows which deal was won, and for how much. It does not know which campaign brought it in. One workflow, one authorization header, and both halves of the story meet.
What HubSpot sends, what Subtraq replies
201
POST /api/v1/sales — Authorization: Bearer stq_sk_… headers: { Authorization: 'Bearer stq_sk_…', 'Content-Type': 'application/json' } { "space": "boulangerie-martin", "amount": 430000, "currency": "EUR", "invoiceId": "deal-18452119", "email": "claire@exemple.fr" } → 201 { ok: true, attributed: true }
The amount is in cents: $4,300 is written 430000. Subtraq never puts a decimal in a money field. And attributed tells the truth: true when the sale found its link, false when it did not — never an invented origin.
Check this before you start
The webhook action is not available on every plan
If your portal does not have access, nothing is lost: a workflow can notify Zapier, Make, or n8n, and the go-between sets the authorization header. One more link in the chain, one more place it can break, but the result in the report is the same.
Check now rather than at the sixth setting. A plan that does not carry the action does not display it: you then assume you looked in the wrong place.
Source: webhooks in HubSpot workflows.
Where "Send a webhook" lives
According to the HubSpot Knowledge Base, the Send a webhook in workflows is available on Data Hub Professional and Enterprise — formerly called Operations Hub. It appears in the "Data ops" section of the editor.
In HubSpot, 7 steps
From the "Closed won" stage to the attributed sale
Nothing to install, nothing to publish. One workflow, one action, one header: HubSpot can set the authorization Subtraq requires all by itself.
In Subtraq, create a server key
Settings → API keys. It starts with stq_sk_, carries the events:write permission, and is shown only once. Also note the client workspace slug, visible in the dashboard URL.
In HubSpot, create a deal-based workflow
Set the trigger on the Deal stage property and the value Closed won. The internal ID of this stage depends on the portal: HubSpot exposes it through its pipelines API if you need to read it.
Add the "Send a webhook" action
It is in the "Data ops" section of the workflow editor. Method POST, URL https://subtraq.co/api/v1/sales.
Set authentication to "API key"
The action's Authentication section asks for a key name and a value, placed as a request header. Name: Authorization. Value: Bearer followed by the server key. This setting is what replaces, in HubSpot, the header most tools cannot set.
Choose "Customize request body"
By default HubSpot sends all deal properties, which Subtraq will reject. Build the body field by field: space, amount, currency, invoiceId, email. The deal amount is in main units on the HubSpot side: it must arrive in cents.
Put the record ID in invoiceId
The hs_object_id property — the deal's Record ID — is stable and unique. It's the ideal idempotency key: a deal moved back to Closed Won after an undo does not count twice.
Move a test deal to Closed Won
The workflow history shows the reply. Subtraq replies 201 for a new sale, 200 for a duplicate, and in both cases says whether the sale found its source link.
Paths recorded in the HubSpot Knowledge Base on 12 September 2026 — the webhook action and default deal properties. Interfaces change: if what you see no longer matches, the source takes precedence.
The best part of this guide
Tracing a contact's source link from the form
Create a contact property with the internal name st_id and place it as a hidden field on the form: it fills itself when the visitor arrives through a tracked link. Then send it in the clickId field of the request, instead of or in addition to the email.
The difference is real. The email matches a person if they gave the same address on both sides and if the click is still within the window. The click ID matches the click itself, and needs no guessing.
Both can travel together: the route accepts email, externalId, and clickId in the same request, and needs only one of the three.
Sources: hidden fields and populating fields via URL parameter, recorded 12 September 2026.
The click enters through the form
HubSpot documents hidden form fields and automatic field population via URL parameter, which matches the property's internal name to the parameter name. A Subtraq link passes a parameter named st_id.
The annoying cases, dealt with straight
A sales cycle is not a supermarket checkout. Here is what Subtraq does, and what it does not.
The deal closes six weeks after the first click. Is it still attributed?
That depends on the client workspace attribution window: thirty days by default, adjustable. Beyond it, the sale is recorded but not attributed. For long cycles, extend the window before connecting: it does not backfill.
A deal moves from Closed Won back to open, then to Closed Won again.
The workflow fires a second time, but the record ID has not changed: the same invoiceId arrives, Subtraq recognises the duplicate, replies 200, and adds nothing. That is exactly the case the field exists for.
The deal amount changes after the fact.
It will not be corrected on its own, and that is a known limit: the route writes a sale, it does not update one. The same invoice ID is treated as already processed. For a revised amount, send a second sale with a distinct ID and an eventName that says what it is.
What about a lost deal or a refund?
Subtraq does not accept a negative amount and has no cancellation call. A lost deal simply is not sent; a refund is tracked with a zero-amount event and corrected by hand in the report. Better to say that than to imply automatic compensation.
Frequently asked questions
Does a HubSpot app need to be installed?
No. Nothing to publish, no development. The webhook action is part of the workflow editor on the plans that include it.
Can you trigger on a contact instead of a deal?
Yes, and it is the right choice when what you are measuring is a lead rather than a sale. The principle does not change: one webhook action, one authorization header, one body built by hand.
Can you send a lead with no amount?
The sales route expects an amount. For a lead with no figure, the simplest path is still the Subtraq link pasted into the form's redirect field: the form submission then becomes a conversion, with no API call.
Where do you see that the request went through?
In the HubSpot workflow history, which stores the reply. And in Subtraq, where the conversion appears with its source link — or without one, if it could not be attributed.
Is the server key visible to the end client?
No. It lives in the workflow authentication setting, on the HubSpot side, and never passes through a browser. That is also why amounts never go through the page tracker.
Without Data Hub Professional, use a go-between
A workflow that notifies Zapier, Make, or n8n, and the go-between sets the Authorization header. The result in the report is identical.
The Zapier guideThe next Closed Won can say where it came from
Create the account, get a server key, add the action to the workflow. The first Closed Won does the rest.
Create a free account