Lead attribution webhook

Google Analytics tells you a session came from ChatGPT. It does not tell you that the session became a lead, because the lead is created in your form provider or your CRM, after the session ends.

The lead attribution webhook closes that gap. You post the lead to Heading with the referrer or utm_source you captured on the visit. Heading matches it to the AI platform and counts it in AI-attributed leads on Analytics → Traffic.

Attribution fails quietly. A sender that signs the wrong bytes returns a 401 into your own logs and nothing appears in Heading, which looks the same as a quiet month. So every attempt is recorded, accepted or rejected, and the delivery log on the Traffic page shows what happened to each one.

Before you start

You need one endpoint and one signing secret, both per property. Open Analytics → Traffic, find the Lead attribution webhook under Data sources, and select Set up. The first step of that dialog holds both values. Team owners and admins can access these credentials.

Select Copy for LLM from any setup step to copy the endpoint, payload fields, signing examples, verification steps and troubleshooting guidance. Paste the guide into your preferred LLM for help adapting it to your form provider, CRM or backend. The signing secret is excluded; copy it privately into your server environment.

The secret is derived from the property, so it does not expire and it is not rotated per property. Treat it as a server-side credential. Store it in your environment, not in your code.

Send an event

{
  "contact": "jane@example.com",
  "email": "jane@example.com",
  "sessionId": "sess_8f2c1a",
  "landingPath": "/pricing",
  "referrer": "https://chatgpt.com/"
}

Worked examples

Each example reads the secret from an environment variable called HEADING_WEBHOOK_SECRET. Replace ENDPOINT with the endpoint from the setup dialog.

# Name the delivery, stamp it, and sign the exact bytes you send.
WEBHOOK_ID=$(uuidgen)
TIMESTAMP=$(date +%s)
BODY='{"contact":"jane@example.com","landingPath":"/pricing","referrer":"https://chatgpt.com/"}'
SIGNATURE=$(printf '%s.%s.%s' "$WEBHOOK_ID" "$TIMESTAMP" "$BODY" \
  | openssl dgst -sha256 -hmac "$HEADING_WEBHOOK_SECRET" -r \
  | cut -d' ' -f1)

curl -X POST "$ENDPOINT" \
  -H 'content-type: application/json' \
  -H "x-webhook-id: $WEBHOOK_ID" \
  -H "x-webhook-timestamp: $TIMESTAMP" \
  -H "x-webhook-signature: $SIGNATURE" \
  -d "$BODY"

import { createHmac, randomUUID } from "node:crypto";

const ENDPOINT = process.env.HEADING_WEBHOOK_ENDPOINT;
const SECRET = process.env.HEADING_WEBHOOK_SECRET;

// Retrying? Pass the same webhookId and you get the same lead back, once.
export async function sendLead(lead, webhookId = randomUUID()) {
  // Serialise once, then sign that exact string with the id and timestamp.
  const body = JSON.stringify(lead);
  const timestamp = String(Math.floor(Date.now() / 1000));
  const signature = createHmac("sha256", SECRET)
    .update(`${webhookId}.${timestamp}.${body}`, "utf8")
    .digest("hex");

  const response = await fetch(ENDPOINT, {
    body,
    headers: {
      "content-type": "application/json",
      "x-webhook-id": webhookId,
      "x-webhook-timestamp": timestamp,
      "x-webhook-signature": signature,
    },
    method: "POST",
  });

  const result = await response.json();
  if (!response.ok) {
    // Every rejection names its reason and the fix.
    throw new Error(`${result.error}. ${result.hint}`);
  }
  return result;
}

import hashlib
import hmac
import json
import os
import time
import urllib.request
import uuid

ENDPOINT = os.environ["HEADING_WEBHOOK_ENDPOINT"]
SECRET = os.environ["HEADING_WEBHOOK_SECRET"].encode()


# Retrying? Pass the same webhook_id and you get the same lead back, once.
def send_lead(lead, webhook_id=None):
    # Serialise once, then sign those exact bytes with the id and timestamp.
    webhook_id = webhook_id or str(uuid.uuid4())
    timestamp = str(int(time.time()))
    body = json.dumps(lead, separators=(",", ":")).encode()
    message = f"{webhook_id}.{timestamp}.".encode() + body
    signature = hmac.new(SECRET, message, hashlib.sha256).hexdigest()

    request = urllib.request.Request(
        ENDPOINT,
        data=body,
        headers={
            "content-type": "application/json",
            "x-webhook-id": webhook_id,
            "x-webhook-timestamp": timestamp,
            "x-webhook-signature": signature,
        },
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)

<?php

$endpoint = getenv('HEADING_WEBHOOK_ENDPOINT');
$secret = getenv('HEADING_WEBHOOK_SECRET');

// Encode once, then sign that exact string with the id and timestamp.
// Retrying? Reuse the same id and you get the same lead back, once.
$webhookId = bin2hex(random_bytes(16));
$timestamp = (string) time();
$body = json_encode([
    'contact' => 'jane@example.com',
    'landingPath' => '/pricing',
    'referrer' => 'https://chatgpt.com/',
]);
$signature = hash_hmac('sha256', "$webhookId.$timestamp.$body", $secret);

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'content-type: application/json',
        'x-webhook-id: ' . $webhookId,
        'x-webhook-timestamp: ' . $timestamp,
        'x-webhook-signature: ' . $signature,
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    $result = json_decode($response, true);
    throw new RuntimeException($result['error'] . '. ' . $result['hint']);
}

Payload fields

Any other key is dropped. The response lists what it dropped in ignoredFields, and if a dropped key looks like a field under another name (utm_source for utmSource, referer for referrer), it comes back in fieldSuggestions with the field it should have been.

What happens to the lead

Heading classifies referrer first, then utmSource, against the AI platforms it knows: ChatGPT (chatgpt.com, chat.openai.com), Claude (claude.ai), Gemini (gemini.google.com, bard.google.com), Perplexity (perplexity.ai), and Microsoft Copilot (copilot.microsoft.com). Subdomains match.

• Classified. The lead is matched to that platform and counted in AI-attributed leads for the day it arrived.
• Not classified. The lead is stored and shown in the recent leads feed, and it is not counted as AI-attributed.

Google AI Overview is deliberately absent. It arrives from google.com with no AI-specific referrer, so we cannot verify it as AI-referred, and we would rather show you nothing than a number we cannot stand behind.

Heading deduplicates on x-webhook-id, and on nothing else. Post the same delivery id twice and the second request returns the first lead, with a duplicate_event warning and no second lead stored. Post two identical bodies under two different ids and you get two leads, because two people can fill in the same form.

The window is the property's retained delivery log, the most recent 50 attempts. Beyond that the timestamp window is what stops a replay: a delivery signed more than five minutes ago is rejected outright.

Responses

A successful request returns 200 with the stored lead:

{
  "leadId": "0f5b…",
  "matched": true,
  "platform": "chatgpt",
  "warnings": [],
  "ignoredFields": [],
  "fieldSuggestions": []
}

Every rejection returns the same three keys: error (what happened), hint (what to change), and reason (a stable code you can branch on).

Retry on 500 and 503, reusing the same x-webhook-id and re-stamping and re-signing with a fresh timestamp. Do not retry a 401 or 413: the same request will be rejected the same way. Of the 400s, only stale_timestamp is worth retrying, and only with a new timestamp.

Verify that it is working

The Webhook delivery log panel on the Traffic page holds the most recent 50 attempts for the property, and shows the 20 newest. Each row carries the response code, what the endpoint did with it, and, for a rejection, the reason and the fix.

The integration card above it reads its status from the same log:

Request bodies are kept only for attempts that passed the signature check, so an unsigned caller cannot write content into your dashboard. A 401 row shows the reason and no body.

What this does not do

• It does not send anything to you. There are no outbound webhooks from Heading yet.
• It does not queue or retry on your behalf. If your request fails, your sender retries it.
• It does not rotate secrets per property. Rotating requires a deployment-wide change, which rotates every property's secret at once.
• It does not accept utm_source and other snake_case keys. It tells you when you sent them, and drops them.