Webhook API

If you prefer to send conversion events from your server rather than the browser, you can POST directly to the Pruuv webhook endpoint. This is useful when you already have lead data in a CRM or backend system and want to forward it to Pruuv without adding JavaScript to your pages.

Authentication

Pruuv checks the token only on requests that come from a browser — any request with an Origin header, such as a Pruuv.track()call. Those must send the stage's token as Authorization: Bearer …, and must come from a domain in the Allowed domains list under Settings → Pixel SDK (when the list is not empty).

Requests from a server have no Origin header. Pruuv accepts them without checking a token: the stage ID in the URL is all they need, and only the hourly rate limit applies. So treat your stage IDs as private. Sending the token from your server anyway is fine.

Each stage has its own token. Find it in Settings → Funnel & Data source → Funnel: open the stage and look under Webhook endpoint. The app shows only its first 8 characters, so ask your Pruuv contact for the full token.

Endpoint

POST https://ai.pruuv.com/api/webhooks/funnel/{stageId}
Content-Type: application/json
Authorization: Bearer YOUR_WEBHOOK_TOKEN    # checked on browser requests only

Example request

curl -X POST https://ai.pruuv.com/api/webhooks/funnel/YOUR_STAGE_ID \
  -H "Authorization: Bearer YOUR_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference":    "CRM-REF-001",
    "utm_source":   "google",
    "utm_medium":   "cpc",
    "utm_campaign": "brand-search",
    "gclid":        "EAIaIQobCh...",
    "revenue_value": 250,
    "currency":     "GBP"
  }'

Payload reference

All fields are optional except reference. An optional field may be omitted, sent as null, or sent as an empty string — all three mean “not provided” and are stored as no value. reference itself must be a non-blank string.

Responses

Deduplication and enrichment

Events are deduplicated on the combination of stage_id + reference (+ item_reference if present) using a unique index — this is a permanent deduplication, not a time-window. Sending the same reference twice will never create two rows. This makes it safe to retry on network errors.

However, if the second event arrives with new data that the first event lacked — for example, a CRM posts UTMs first and the Pruuv Pixel fires moments later with fbc/gclid/ttclid — Pruuv performs an enrichment merge: it fills in any NULL fields on the existing row from the new payload, without overwriting anything already stored. The response is still { received: true, duplicate: true }, but the row now has both datasets. A merge never itself sends anything, and never re-sends a conversion that was already sent. If the lead has not been sent yet, the fields the merge added (a click ID or an email, say) are used when it is. A merge cannot help a lead get matched to an ad account, though: UTM parameters are not merged.

Enrichable fields: fbc, fbp, gclid, wbraid, gbraid, ttclid, msclkid, li_fat_id, click_timestamp, email_hash, phone_hash, the name, date-of-birth and postcode hashes, user_agent, event_source_url, the visitor's IP address, revenue_value, currency, identity_user_id, first_touch, event_id, pruuv_visitor_id. A repeat post that adds the visitor ID also fills in the click IDs and browser details of that browser.

To get the browser's click IDs onto the lead before the conversion is sent, call Pruuv.identify() in the browser before your server posts the lead. See Pixel SDK → How Pruuv links the pixel to your CRM.

Integration paths compared