Set up webhooks

Steps

1. 1

   Pick an event

   lead:bought fires when your organisation buys a lead; lead:deleted fires when a lead you bought has its personal data erased (privacy request or retention expiry), so you can erase your copy. Every request carries the event in the x-zolar-event header.

2. 2

   Create an endpoint

   Add a secret header, such as Authorization, so your system can verify the request comes from zolar.

   curl Copy

   curl -X POST https://demo.api.lead.zolar.tech/api/public/v2/installer/webhooks \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]" \
     -H "Content-Type: application/json" \
     -d '{
       "event": "lead:bought",
       "url": "https://crm.example.com/zolar/leads",
       "headers": [
         { "name": "Authorization", "value": "Bearer [YOUR WEBHOOK SECRET]" }
       ]
     }'

   The response is the endpoint with its id; header values are never returned, only headerNames.

3. 3

   Test it

   zolar sends a sample event matching the endpoint's event (a bought lead or a deletion) and returns the status and response body your system answered with.

   curl Copy

   curl -X POST https://demo.api.lead.zolar.tech/api/public/v2/installer/webhooks/[WEBHOOK ID]/test \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]"
   
   # { "status": 200, "body": "ok" }

   Status 501 means your endpoint could not be reached; 555 means a custom body could not be filled.

4. 4

   Manage endpoints

   These are the same endpoints as in the portal under Settings → Integrations.

   curl Copy

   # List
   curl https://demo.api.lead.zolar.tech/api/public/v2/installer/webhooks \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]"
   
   # Replace (leave out "headers" to keep the stored ones; [] removes them)
   curl -X PUT https://demo.api.lead.zolar.tech/api/public/v2/installer/webhooks/[WEBHOOK ID] \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]" \
     -H "Content-Type: application/json" \
     -d '{ "event": "lead:bought", "url": "https://crm.example.com/zolar/v2" }'
   
   # Delete
   curl -X DELETE https://demo.api.lead.zolar.tech/api/public/v2/installer/webhooks/[WEBHOOK ID] \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]"

   PUT is a full replace: a left-out name, enabled or bodyTemplate returns to its default.

5. 5

   Send a custom body

   Optional

   Set bodyTemplate to a JSON template if your system expects its own shape: a JSON object up to 16 KB, with {{ lead.firstName }} or {{ path | filter }} placeholders in string values. A value that is exactly one placeholder keeps its type; unknown variables or filters are rejected on save.

   All variables and filters are listed under Body template reference below; the portal's template editor (Custom body) shows the same list with a live preview. If a template can't be filled for a lead, nothing is sent and the run shows as failed under Recent runs.

Standard payload

Without a custom body, a lead:bought request carries this JSON; id is your leadOfferId.

{
  "id": "00000000-0000-4000-8000-000000000001",
  "salutation": "woman",
  "firstName": "Erika",
  "lastName": "Musterfrau",
  "email": "erika@example.org",
  "phone": "+4915100000000",
  "country": "DE",
  "city": "Musterstadt",
  "postalCode": "12345",
  "street": "Musterstraße 12",
  "properties": {
    "interest": { "pv": "interestNew", "battery": "interestNew" },
    "building": { "type": "residential", "isOwner": true }
  },
  "marketPlace": "My Marketplace"
}

{
  "id": "00000000-0000-4000-8000-000000000001",
  "leadId": "00000000-0000-4000-8000-000000000002",
  "event": "lead:deleted",
  "reason": "gdpr",
  "deletedAt": "2026-10-23T09:30:00.000Z",
  "marketPlace": "My Marketplace"
}

reason is gdpr or retention.

Delivery and limits

• A 2xx answer counts as delivered. There are no automatic retries: a request that fails, times out (10 s) or gets a non-2xx answer is not sent again. Redirects are not followed.
• Failed runs show under the endpoint's Recent runs in Settings → Integrations, where Retry resends them by hand and Send past purchases delivers earlier purchases.
• Up to 20 webhook endpoints per organisation.
• Host, Content-Length, Transfer-Encoding, Connection and x-zolar-event can't be set as headers; each name only once.
• The URL must use http or https on port 80 or 443 and point at a public host — not localhost or a private, loopback or link-local address.
• Permissions: Read webhooks to list, Manage webhooks to create, replace, delete and test.

Body template reference

Templates may be up to 16 KB. Below an object or array of lead.properties marked "any path below it too", paths that are not listed still work; they are filled with the lead's value, or null.