Pixels and macros

After this page you can close the loop on paid media: when a call converts, the network that sold you the click is told, in its own URL with its own parameter names. A pixel is a request the platform makes to somebody else's server when an event fires, with values from the call filled in by macros.

A webhook sends your server a fixed JSON envelope. A pixel sends their server exactly the request they documented. Underneath they are the same machinery — the same queue, the same retries, the same delivery log, the same replay — and both are on plans that include webhooks and pixels; see pricing.

A pixel in one line

https://ads.example.com/conversion?click={{tag.gclid}}&value={{call.revenue}}&ref={{call.ref}}&caller={{caller.e164}}

When call.converted fires, each {{namespace.field}} is replaced with that call's value and the request is made. The click id the visitor arrived with — captured by DNI as a tag — goes back to the platform that sold you the click, with the revenue beside it, and the loop is closed.

GET /conversion?click=Cj0KCQjw&value=42.00&ref=CA-482137&caller=9c1185a5c5e9fc54 HTTP/1.1
Host: ads.example.com
User-Agent: buy3-webhooks/1
buy3-event: call.converted
buy3-request-id: req_5f0c2a91b7d34e10
buy3-attempt: 1

Three things happened there that are worth naming. {{tag.gclid}} expanded because the tag is yours and the pixel is yours. {{call.revenue}} arrived as dollars, which is what a value= parameter takes. And {{caller.e164}} came out as a hash rather than a phone number, without anybody choosing that — see Caller identity never reaches a URL.

Setting one up

1. 1

   Get the partner's URL

   From their documentation, with their parameter names. Paste it whole and then replace the values with macros — do not retype it, because a partner's parameter names are frequently not what you would have guessed.

2. 2

   Choose the event

   call.converted for a sale. call.completed for every finished call, converted or not, when a partner wants to hear about all of them. Firing a conversion pixel on call.connected reports value=0.00, correctly and uselessly — money exists only once the call has settled.

3. 3

   Create it

   kind: "pixel". The method defaults to GET, which is what an ad network's conversion URL usually is.

   Create a pixelCopy

   curl -X POST "https://api.buy3.io/api/tracking/webhooks" \
     -H "Authorization: Bearer $BUY3_SESSION_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Search network — conversions",
       "kind": "pixel",
       "method": "GET",
       "url": "https://ads.example.com/conversion?click={{tag.gclid}}&value={{call.revenue}}&ref={{call.ref}}",
       "eventPattern": ["call.converted"],
       "campaignId": "6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d"
     }'

4. 4

   Narrow it if it belongs to one campaign

   campaignId or publisherId limits the pixel to that campaign's or that publisher's calls. A pixel for one advertiser's account should not fire on another's traffic.

   201 CreatedCopy

   {
     "webhook": {
       "id": "e4f3a2b1-9c8d-4e7f-b6a5-4d3c2b1a0f9e",
       "name": "Search network — conversions",
       "kind": "pixel",
       "url": "https://ads.example.com/conversion?click={{tag.gclid}}&value={{call.revenue}}&ref={{call.ref}}",
       "method": "GET",
       "eventPattern": ["call.converted"],
       "status": "active",
       "campaignId": "6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d",
       "campaignName": "Acme Health — Inbound",
       "signed": false,
       "secretHint": null,
       "stats": { "window": "24h", "attempts": 0, "delivered": 0, "failed": 0, "p50": 0, "p95": 0, "lastStatus": null, "lastOk": null, "lastAt": null }
     },
     "notes": []
   }

5. 5

   Send a test and read the log

   The delivery log records the URL after expansion, so you can see exactly what the partner received rather than what your template says.

How macros behave

• A macro is a namespace and a field: {{call.ref}}, {{caller.state}}, {{campaign.name}}, {{tag.utm_source}}. There are no expressions, sums or conditions — a template can only ever insert a value.
• A macro with no value becomes an empty string, never the literal braces. A partner's parser copes with &age=; it does not cope with &age={{tag.age}}.
• Values are encoded for where they land: percent-encoded in a URL, JSON-escaped in a JSON body. You never escape anything yourself, and a tag containing an & can never add a parameter of its own.
• Spaces inside the braces are fine, and three opening braces send a literal {{ through for a partner whose own template language uses them.
• A macro the vocabulary does not have is refused when you save, naming it. Rule two is right on the wire and useless in an editor: a silent empty parameter would report nothing for a month before anybody noticed.

{
  "error": "Validation failed",
  "code": "invalid",
  "details": {
    "macros": "unknown macro: {{call.durration}} — GET /api/tracking/webhooks/events lists the ones a pixel can use"
  },
  "requestId": "req_0f1e2d3c4b5a6978"
}

Every macro a pixel can use

This is the whole vocabulary, and it is exactly what the save-time check accepts. The In a URL column is the privacy rule below, applied token by token; it does not apply to a POST body.

Event and call

Caller

Number, campaign, publisher, buyer and target

Tags and time

Caller identity never reaches a URL

A URL ends up in access logs, referrer headers and analytics pipelines on both sides. A caller's phone number there is a disclosure nobody chose, so it is prevented in code rather than discouraged in a note.

The hash is stable: the same caller gives the same sixteen characters every time, for ever. A partner can de-duplicate on it, suppress on it and join on it, and cannot dial it or reverse it into a number they do not already hold.

POST pixels and body templates

Some partners want a POST with a JSON body rather than a query string. Set method to POST and give a bodyTemplate; the URL is still expanded in URL mode, and the body is expanded in the mode its content type implies.

{
  "external_id": "{{call.ref}}",
  "phone": "{{caller.e164}}",
  "state": "{{caller.state}}",
  "seconds": {{call.duration}},
  "revenue": "{{call.revenue}}",
  "source": "{{publisher.name}}",
  "click_id": "{{tag.gclid}}",
  "at": "{{call.ended_at}}"
}

{
  "external_id": "CA-482137",
  "phone": "+14155550142",
  "state": "CA",
  "seconds": 184,
  "revenue": "42.00",
  "source": "Northwind Media",
  "click_id": "Cj0KCQjw",
  "at": "2026-09-20T14:06:23.000Z"
}

What a pixel may not do

• A macro cannot be in the host. https://{{tag.host}}/track is refused: whoever controls a tag would be choosing where this server sends a request, and the address check would have vetted a host that is not the one called. Macros belong in the path and the query string.
• The address is checked twice — when you save, against the template expanded over a sample call, and again at every send, because DNS is yours to change. Hosts resolving to private, loopback or link-local ranges are refused.
• Redirects are not followed. A 3xx is recorded as the failed delivery it is. Ask the partner for the final URL.
• Reserved headers stay ours. Hop-by-hop headers and anything starting buy3- cannot be set, so a receiver trusting buy3-signature is never reading a value a customer typed.
• Bidding macros are refused, as are unknown ones. Both are caught at save time.

Worked example: closing the loop on paid search

You buy clicks, the landing page shows a pool number, a visitor calls it, and three minutes later the call converts. The network needs to hear about it against the click it sold you.

1. Capture the click id. The DNI snippet records the landing page's query string on the session, so gclid arrives as a tag on any call from that visitor. Check a real call in the call log and confirm the tag is there before you build anything on it.
2. Create the pixel on call.converted, narrowed to the campaign that runs those ads, with the URL above.
3. Send a test. The test uses your newest real call, so the log shows a real gclid rather than a placeholder — which is what proves the capture worked.
4. Read the expanded URL in the delivery log and compare it with the partner's documentation, parameter by parameter.
5. Watch the endpoint's 24-hour tiles for a day. A network that answers 200 to everything including nonsense will look healthy here, so confirm the conversions are arriving in their reporting too.

Next steps