Goal conversion pixel recipes

A pixel_fire goal fires when a third-party page (your checkout “thank you”, your signup confirmation, your partner’s success screen) renders a signed <img src>. This page walks the full cycle on the wire — mint the signature, embed the pixel, probe it with curl, close the conversion loop, then covers the short-link redirect (GET /l/{code}) in the same frame. The public pixels, redirects, and short links concept page is the contract; the Goals API reference is the per-endpoint shape. Nothing here ships an API key into a public URL. The <img> hits an anonymous, root-mounted endpoint and authenticates purely with the HMAC in the query string.

Task index

#	Recipe	Ops used
1	Create a `pixel_fire` goal	`POST /api/v1/analytics/goals`
2	Mint the HMAC sig for a goal+contact pair	server-side / hash helper
3	Embed the pixel on a checkout/signup page	`<img>` in HTML
4	Probe the pixel and close the loop with curl	`GET /g/{goalId}/{contactId}.gif`, `GET /api/v1/analytics/goals/:id/conversions`
5	Short-link redirect probe	`GET /l/{code}`
6	Replay and abuse notes	—
7	Sandbox flavor	—

1. Create a `pixel_fire` goal

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/analytics/goals \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout complete",
    "type": "pixel_fire"
  }'

The response carries the goal’s embed hint. pixel_url is the template you fill in:

{
  "data": {
    "id": "goal_7XQ2W",
    "name": "Checkout complete",
    "type": "pixel_fire",
    "pixel_url": "https://api.orbit.devotel.io/g/goal_7XQ2W/{contact_id}.gif?sig=<hmac(goalId:contact_id:tenant_schema)>&schema=<tenant_schema>"
  },
  "meta": { "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ", "timestamp": "2026-10-03T12:00:00.000Z" }
}

Keep data.id — every sig below signs it. The Goals surface in the dashboard shows the same template beside the goal, so an operator can copy it without reading the API.

2. Mint the HMAC sig

The pixel URL’s sig is a hex HMAC-SHA256 over the pipe-joined tuple goalId:contactId:tenantSchema. The tenant schema is part of the signed payload — a leaked URL can’t be replayed under a different schema by swapping the ?schema= param. Mint server-side (never in a browser bundle — the signing key is your DEVOTEL_API_SECRET_KEY, the same key the API client secrets derive from):

import { createHmac } from "node:crypto";

const sig = createHmac("sha256", DEVOTEL_API_SECRET_KEY)
  .update(`${goalId}:${contactId}:tenant_ac4f2`)
  .digest("hex");

For each checkout render, that line produces the query-string value to splice into the pixel_url template. The Node SDK and the dashboard’s Goals → embed panel wrap the same call — the hash helper reads simpler here than a one-line import.

3. Embed the pixel

On the checkout or signup “thank you” page template — the page a merchant already renders after the order posts — drop the tag with the minted sig spliced in:

<img width="1" height="1"
     src="https://api.orbit.devotel.io/g/goal_7XQ2W/contact_9fMRA.gif?sig=9f0e2d…&schema=tenant_ac4f2"
     alt="" />

The 1×1 transparent GIF answers 200 on every render — a forged or malformed sig doesn’t break the page and doesn’t render a broken-image glyph on the buyer’s screen. It just doesn’t record.

4. Probe the pixel and close the loop

Two curl steps — verify the GIF contract, then read the goal’s /conversions listing to confirm the row landed:

cURL

curl -i "https://api.orbit.devotel.io/g/goal_7XQ2W/contact_9fMRA.gif?sig=9f0e2d…&schema=tenant_ac4f2"

HTTP/1.1 200 OK
Content-Type: image/gif
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
<43-byte transparent GIF>

Close the loop — the conversion record, sourced from the pixel:

cURL

curl -s "https://api.orbit.devotel.io/api/v1/analytics/goals/goal_7XQ2W/conversions?limit=5" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

{
  "data": [
    {
      "goal_id": "goal_7XQ2W",
      "contact_id": "contact_9fMRA",
      "conversion_time": "2026-10-03T12:00:04.512Z",
      "value_cents": null,
      "metadata": { "source": "pixel", "ip": "203.0.113.4", "user_agent": "Mozilla/5.0 …", "referer": "https://your-shop.example/checkout/success" }
    }
  ],
  "meta": { "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ", "timestamp": "2026-10-03T12:00:06.000Z" }
}

metadata.source: "pixel" is the tell that the loop came through GET /g/ and not a webhook/manual call. A forged probe — a sig that doesn’t match goalId:contactId:schema — still answers 200 with the GIF, but the /conversions listing shows nothing for it. That asymmetry is the whole security story.

5. Short-link redirect probe

A short link (POST /api/v1/links returns one) resolves anonymously through the same root-mounted surface. Probe it the way a browser would — ask for HTML:

cURL

curl -i -H "Accept: text/html" "https://api.orbit.devotel.io/l/AbC123"

HTTP/1.1 302 Found
Location: https://example.com/promo?utm_campaign=may26

An unknown code answers with a branded HTML error page when the caller asks for HTML, or a JSON envelope when it asks for JSON. Browsers always send Accept: text/html and see the friendly page; your probe sees the envelope:

HTTP/1.1 404 Not Found

{ "error": { "code": "LINK_NOT_FOUND", "message": "Unknown or malformed link", "status": 404 } }

The short-link family rate-limits tighter than the pixel families (60 req/IP/min vs 120) because a public redirect is trivially pastable.

6. Replay and abuse notes

The signature binds goalId + contactId + tenantSchema. A replay against a different contact or a swapped ?schema= fails verification. Leaking a pixel URL exposes exactly one goal+contact conversion — never the class.
Per-IP rate limits. The pixel families ride at 120 requests/IP/minute; /l/ short links at 60. A loop that fans your own pixel out from one address throttles itself.
Idempotent. Re-rendered pixels don’t double-write; the /conversions listing collapses to the first hit. First-event-wins — a replayed GET can’t corrupt the goal’s totals.
Fail-closed on any tamper. No sig, no schema, malformed schema, mismatched HMAC — all answer 200 + GIF and record nothing. The GIF always comes back.

7. Sandbox flavor

Run every step here with dv_test_sk_… before you trust the sig-minting code against live. A sandbox key records sandbox conversions on the same wire, so you can prove the full cycle — mint, embed, curl, verify — without touching a real goal. One invalid-sig branch is the check that matters: send a sig of all zeros and confirm the /conversions listing stays empty while the GIF still returns.

For the full pixel/redirect/short-link contract — wire-level response shapes, signing model, and the idempotency model — see public pixels, redirects, and short links. The Goals API reference has the goal CRUD and conversions listing shapes.

WhatsApp

Developer console

Guides

Messaging Controls

Audience & Support Tools

Goal conversion pixel: mint the sig, embed the <img>, verify with curl

Goal conversion pixel recipes

Task index

1. Create a `pixel_fire` goal

2. Mint the HMAC sig

3. Embed the pixel

4. Probe the pixel and close the loop

5. Short-link redirect probe

6. Replay and abuse notes

7. Sandbox flavor

​Goal conversion pixel recipes

​Task index

​1. Create a pixel_fire goal

​2. Mint the HMAC sig

​3. Embed the pixel

​4. Probe the pixel and close the loop

​5. Short-link redirect probe

​6. Replay and abuse notes

​7. Sandbox flavor

Goal conversion pixel recipes

Task index

1. Create a `pixel_fire` goal

2. Mint the HMAC sig

3. Embed the pixel

4. Probe the pixel and close the loop

5. Short-link redirect probe

6. Replay and abuse notes

7. Sandbox flavor