Custom webhooks

Custom webhooks let you send conversion events (purchases, leads, sign-ups, etc.) directly to TrustData from your server, CRM, or any platform that can make HTTP requests.

How it works

Instead of relying on browser-side tracking, you POST a JSON payload to a TrustData endpoint. TrustData matches the event to a tracked session and attributes it to the correct ad campaign.

Your server → POST /webhooks/custom/{attribution_id}/{topic}
                     ↓
          TrustData matches to visitor session
                     ↓
          Attribution credit assigned to campaign
                     ↓
          Conversion forwarded to ad platforms (if enabled)

Setup

Enable webhook receiving

1. Go to Settings → Attribution IDs → select your ID
2. Open the Webhooks tab
3. Click Enable

Once enabled, the endpoint URL and API key section appear.

Generate an API key

1. Enter a name for the key (e.g., Backend prod, Shopify prod)
2. Click Generate Key
3. Copy the key immediately — it is shown only once

Keys use the format td_wh_<random>. Only the prefix is stored in TrustData; the full key cannot be recovered after creation. If lost, revoke it and generate a new one.

Endpoint

POST https://t.trustdata.tech/webhooks/custom/{attribution_id}/{topic}

Topics

Authentication

Payload

The webhook payload uses the same schema as the JavaScript SDK — same field names, same objects. See the Event schema for the full reference.

A minimal purchase example:

{
  "conversion_id": "ORD-12345",
  "value": 149.99,
  "currency": "USD",
  "user_data": {
    "email": "[email protected]"
  }
}

A complete purchase with all signals:

{
  "conversion_id": "ORD-12345",
  "value": 149.99,
  "currency": "USD",
  "tax": 12.50,
  "shipping": 5.99,
  "discount_code": "SUMMER20",
  "user_data": {
    "email": "[email protected]",
    "phone": "+15551234567",
    "first_name": "Jane",
    "last_name": "Doe",
    "address": {
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  },
  "products": [
    {
      "id": "SKU123",
      "name": "Widget Pro",
      "quantity": 2,
      "price": 49.99
    }
  ],
  "consent": {
    "analytics": true,
    "advertising": true
  }
}

Examples

Purchase

curl -X POST \
  https://t.trustdata.tech/webhooks/custom/YOUR_ATTRIBUTION_ID/purchase \
  -H "Authorization: Bearer td_wh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion_id": "ORD-12345",
    "value": 149.99,
    "currency": "USD",
    "user_data": {
      "email": "[email protected]",
      "phone": "+15551234567"
    },
    "consent": { "analytics": true, "advertising": true }
  }'

Lead

curl -X POST \
  https://t.trustdata.tech/webhooks/custom/YOUR_ATTRIBUTION_ID/lead \
  -H "Authorization: Bearer td_wh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion_id": "lead_abc789",
    "value": 50,
    "currency": "USD",
    "lead_type": "demo_request",
    "user_data": {
      "email": "[email protected]"
    },
    "consent": { "analytics": true, "advertising": true }
  }'

Session matching

TrustData links the incoming webhook to a browser session it has already tracked. The session match is what ties the conversion back to the ad click that drove it.

Matching uses visitor_id — the anonymous ID the JavaScript SDK assigns to the visitor. Pass it from your frontend to your backend when a conversion occurs.

// Frontend: get the visitor ID at checkout
const visitorId = trustdata.getVisitorId();
// Pass visitorId to your backend with the order

{
  "conversion_id": "ORD-12345",
  "visitor_id": "the-id-from-getVisitorId",
  "value": 149.99,
  "currency": "USD"
}

user_data (email, phone, etc.) is used for enhanced conversion forwarding to ad platforms — not for session matching.

If a match is found (session_matched: true in the audit log), the conversion is attributed to the campaign and forwarded to ad platforms.

Viewing webhook activity

The Recent Activity section in the Webhooks tab shows the last 20 requests:

Rate limits

Default limit: 60 requests per minute per API key. Adjustable per key in the dashboard.

Troubleshooting

401 Unauthorized

• Check the header is correctly formatted: Authorization: Bearer td_wh_...
• Verify the API key is active (not revoked)
• Ensure no extra whitespace around the token

404 Not Found

• Verify the attribution ID in the URL is correct
• Confirm webhook receiving is enabled for that attribution ID

429 Too Many Requests

• You have exceeded the rate limit for the API key
• Reduce request frequency or raise the limit in the dashboard

Event not attributed

• Check Recent Activity — if session_matched is false, the webhook was received but not linked to a visitor
• Confirm visitor_id is included — it is the primary matching signal (use trustdata.getVisitorId())
• Confirm the TrustData SDK is installed on your landing pages — sessions need to be tracked first
• Check that the event arrived within the lookback window (default: 30 days from click)