REST Webhook (Custom CRM)

The REST Webhook (Custom CRM Integration) is how you connect NZ Leads to a CRM or internal system that isn’t one of the directly-supported CRMs. NZ Leads sends an HTTP POST request to an endpoint you control every time a lead event happens on a source that uses the webhook - a new lead, new contact info, a new message - and, for voice agents, when a call ends. The payload is a JSON document containing the lead’s details. Every request except the test from the card carries a secret key in a header so your endpoint can verify the request really came from NZ Leads.

ℹ️

This integration requires a developer or someone who can host an endpoint that receives JSON. If you need a no-code route to a custom tool, use Zapier instead. If you just want a team alert, use Slack, SMS, or Telegram.

ℹ️

You set the webhook up once and then choose which sources and voice agents send to it. In Add integration it’s listed as REST webhook under Webhooks and automation. Add it from a source’s Messaging Settings → Integrations tab, from a voice agent’s Integrations section, or from Settings → Integrations in the menu, which lists all your integrations.

What you’ll get

Connecting the Webhook

Add the webhook

In NZ Leads, open the source → Messaging Settings → Integrations tab → Add integration → Create new → REST webhook. The webhook’s window opens. If your account already has a REST webhook integration, pick it on the Use existing tab instead.

Paste your Webhook URL

Enter the public URL (http or https) of the endpoint you want NZ Leads to POST to in Enter your webhook URL and click Save. Addresses on a local or private network are refused. Your endpoint should accept JSON, respond with a 2xx status on success, and be reachable from the public internet.

Copy the Secret key

Saving the URL also creates a secret key. Click the eye icon next to Secret Key: to show it. The key is sent on every request in the X-Secret-Key HTTP header. Copy it into your receiver code and compare it against the incoming header on every request - reject any request where it doesn’t match.

You can Regenerate the secret key at any time. Regenerating replaces the key immediately - requests after that carry the new key, so update your receiver at the same time.

Test webhook endpoint

Expand the saved URL on the card and click Test webhook endpoint to send a sample POST to your URL right now. You’ll see “Webhook endpoint is working correctly!” when your endpoint answers with a 2xx status, or “Webhook test failed” with the reason. The test request does not carry the X-Secret-Key header, so let it through your signature check or check the secret on real lead events instead.

Turn on the Enabled toggle

The integration doesn’t POST anything until Enabled is on.

To send another source’s leads to the same URL, open that source’s Integrations tab → Add integration → Use existing and pick this webhook. You can also tick sources and voice agents under Where it’s used in the webhook’s window. If you added the webhook on the Integrations page, it isn’t used anywhere yet: tick the places under Where it’s used.

Options

Enable

Turns this webhook on or off everywhere it’s used. Default: off. It appears once a URL is saved. To stop sending one source’s leads only, switch the webhook off on that source’s Integrations tab (if the source follows its business, turn on Customize for Location first), or untick the source under Where it’s used.

Webhook URL

The public http or https endpoint that receives the POST. Required. It’s shown as the title of a panel on the card; to change it, delete it and save the new URL.

Secret key

Created when you save the URL; it stays hidden until you click the eye icon. Sent on every request as the X-Secret-Key HTTP header. Your receiver should reject any request whose header doesn’t match the key you configured. Click Regenerate to issue a new one - the old key stops working immediately.

Handing the conversation to your own system

The REST Webhook card has no option to stop NZ Leads’s own messages. If your system takes over the conversation, use Skip welcome message & follow-ups in the source’s Messaging Settings → Conversation Setup (shown while the AI Assistant is off). To answer customers from your own system, send the replies through the Lead Reply API.

Create lead in CRM only when contact info is received

Label: Create lead in CRM only when contact info is received. Default: off.

Create only new leads

Label: Create only new leads. Default: off.

This option looks at the conversation, not at your endpoint: it doesn’t search your endpoint for an existing record.

Notify this integration only after the AI determines the lead is interested

Label: Notify this integration only after the AI determines the lead is interested. Default: off.

Test webhook endpoint

Fires a sample POST to the URL right now (10-second timeout) so you can confirm your endpoint receives it and returns a 2xx status. The sample has no X-Secret-Key header.

Payload Example

The card has an expandable sample JSON block showing the shape of data NZ Leads will POST to your endpoint.

Remove the webhook

Expand the saved URL and click the delete button, then Yes. Clears the webhook URL and secret and turns the integration off.

Sample payload

The request is an HTTP POST with a JSON body. The X-Secret-Key header is set to your secret key. The body looks like:

{
  "message": "New lead created",
  "data": {
    "lead_id": "lead_01HX7Q5W9J2E8K1M3YPABCDEFG",
    "email": "alex@example.com",
    "phone": "+12025550123",
    "firstName": "Alex",
    "lastName": "Rivera",
    "postalCode": "90210",
    "tags": ["Yelp - Downtown"],
    "messages": [],
    "integrations": {}
  }
}

Fields:

When a voice agent that uses the webhook finishes a call, the request looks like this (transcript is left out when there is none):

{
  "message": "Call Finished",
  "data": {
    "phone": "+12025550123",
    "summary": "Customer requested an estimate.",
    "recordingUrl": "https://example.com/recording.wav",
    "transcript": "Agent: How can I help?\nCustomer: I need an estimate."
  }
}

What your endpoint should do

Disconnecting

Regenerating or deleting the URL invalidates the old secret immediately.

Troubleshooting


Questions about the REST Webhook integration? Email support@nzleads.com.

Get Started