Send webhooks to LeadJourney

A webhook is how your own system tells LeadJourney that something happened: a lead came in, a call was booked, a deal was won. You send one POST request with a small JSON body, and LeadJourney matches that event back to the ad click that created the lead.

This is the way to go when the milestone lives in your own software – a custom CRM, your own booking form, an in-house backend – and there's no native connector watching it for you.

When you need a webhook

• You have a native connector for the tool (HubSpot, Pipedrive, Stripe, Calendly and others). Then you don't need any of this – connect it and map the events. See Apps.
• The milestone lives in your own system. Your CRM, your booking system, your backend: send the event yourself with a webhook. That's this article.

Before you start

Three things have to be in place:

1. Tracking is live. Events are matched to the visitor who clicked your ad, so clicks have to be recorded first – see Install the tracking script.
2. The event exists. The type you send has to match an event in your Events Manager. Every workspace starts with Lead and WonClient.
3. You have your credentials. Open Settings → Events → Conversion API:

Anatomy of a request

Every event is one POST with a JSON body:

curl -X POST "https://api.leadjourney.io/api/v1/postback/YOUR-WORKSPACE-ID" \
  -H "Authorization: Bearer YOUR_POSTBACK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Lead",
    "click_id": "8f3c2a1e-4b7d-4c1a-9e2f-6d5b3a7c9e10",
    "email": "[email protected]"
  }'

That's the whole contract: URL + Authorization header + JSON body. Everything below is detail around those three parts.

What you can send

Stick to these fields – they're the ones the Conversion API defines.

The event type

type has to match the event name in the Events Manager character for character, including capitalisation. A typo doesn't create a new event; the call simply won't land where you expect it.

At least one identifier

An event without an identifier can't be attributed. Send whichever of these you have – ideally all three:

• click_id – the strongest match, because it points at one specific ad click. Your system only has it if you captured it when the lead was created. See Read and store the click ID.
• email – the safety net. It also matches leads whose click ID was lost, for example because the visitor switched devices.
• phone – useful for call-driven funnels. Send it in international format (+49170…), so the same person is recognised across systems.

Revenue

Send revenue as a number, not a string, with a dot as the decimal separator: 1499.00, not "1.499,00 €". Your workspace currency decides how that number is displayed in reports.

• revenue is required for WonClient – without it, the deal counts but contributes no revenue to your ROAS.
• cash_collected is for businesses that book a contract value up front but collect in instalments. If both are the same, you can leave it out.
• For a refund, send a negative revenue to correct the total.

Names

first_name and last_name don't affect matching – they enrich the lead record so you recognise who is behind a conversion in your reports.

Custom fields

Anything specific to your business – industry, plan, deal size, lead score – goes into custom_fields. Create each field once under Settings → Events → Custom Fields, then send its exact webhook key:

{
  "type": "WonClient",
  "email": "[email protected]",
  "revenue": 1499.00,
  "custom_fields": {
    "industry": "Software",
    "company_size": 100,
    "deal_size": 1499.00
  }
}

The field has to exist before you send data for it, and its type has to match the value you send – a string for text fields, a number for number and currency fields. Custom fields then become Group By and Filter dimensions in your reports. See Custom fields.

Example payloads

The same endpoint takes every event – only the body changes.

{
  "type": "Lead",
  "click_id": "8f3c2a1e-4b7d-4c1a-9e2f-6d5b3a7c9e10",
  "email": "[email protected]",
  "phone": "+491701234567",
  "first_name": "Anna",
  "last_name": "Schmidt"
}

{
  "type": "BookedCall",
  "click_id": "8f3c2a1e-4b7d-4c1a-9e2f-6d5b3a7c9e10",
  "email": "[email protected]"
}

{
  "type": "WonClient",
  "click_id": "8f3c2a1e-4b7d-4c1a-9e2f-6d5b3a7c9e10",
  "email": "[email protected]",
  "revenue": 1499.00,
  "cash_collected": 499.00,
  "custom_fields": {
    "plan": "Pro"
  }
}

{
  "type": "Refund",
  "email": "[email protected]",
  "revenue": -1499.00
}

Sending it from your code

Hook into the place where the state actually changes – the form handler, the service method that closes a deal, your payment provider's webhook handler – and send one POST per milestone:

await fetch(`https://api.leadjourney.io/api/v1/postback/${process.env.LJ_WORKSPACE_ID}`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LJ_POSTBACK_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "WonClient",
    click_id: deal.contact.ljClickId, // the click ID you stored on the contact
    email: deal.contact.email,
    revenue: deal.amount,
  }),
  signal: AbortSignal.timeout(10_000),
});

$ch = curl_init("https://api.leadjourney.io/api/v1/postback/" . getenv("LJ_WORKSPACE_ID"));
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("LJ_POSTBACK_SECRET"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "type"     => "WonClient",
        "click_id" => $deal->contact->lj_click_id,
        "email"    => $deal->contact->email,
        "revenue"  => $deal->amount,
    ]),
]);
curl_exec($ch);
curl_close($ch);

import os, requests

requests.post(
    f"https://api.leadjourney.io/api/v1/postback/{os.environ['LJ_WORKSPACE_ID']}",
    headers={
        "Authorization": f"Bearer {os.environ['LJ_POSTBACK_SECRET']}",
        "Content-Type": "application/json",
    },
    json={
        "type": "WonClient",
        "click_id": deal.contact.lj_click_id,
        "email": deal.contact.email,
        "revenue": deal.amount,
    },
    timeout=10,
)

curl -X POST "https://api.leadjourney.io/api/v1/postback/$LJ_WORKSPACE_ID" \
  -H "Authorization: Bearer $LJ_POSTBACK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "WonClient",
    "click_id": "'"$CLICK_ID"'",
    "email": "[email protected]",
    "revenue": 1499.00
  }'

Where to fire it in your system

Store the click ID on the contact when the lead is created. Every later event then reads it back from your own database – that's what keeps the whole funnel on one click, even weeks later.

Reliability

• Don't block the user. Send the webhook from a background job or queue, with a timeout of a few seconds. A slow call must never delay a sign-up or a checkout.
• Retry on failure. Treat any non-2xx response as a failure and retry with a short backoff.
• Don't build your own dedupe logic. Use the event modes below – then a retried call won't inflate your numbers.

Repeated calls: duplicates and updates

How a second webhook for the same lead is handled is decided per event in the Events Manager, not in your code:

You set the mode when you create the event – see Events & the Events Manager.

Test and debug

When something doesn't arrive

FAQ

Related articles