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.
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
- An HTTP POST to your endpoint for every lead event of the sources that use the webhook.
- A JSON body with the lead’s identity, contact info, tags, and the conversation history so far.
- An
X-Secret-Keyheader on every request so you can verify the sender. - For voice agents that use the webhook, a Call Finished request after each call.
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.
- When on - your endpoint gets the lead only once the lead has shared a phone number or email, and only if CRMs is checked under Trigger integrations: in the source’s Contact Info tab for that kind of contact info.
- When off - your endpoint gets the lead as soon as the lead first reaches out, even before you have their contact info.
Create only new leads
Label: Create only new leads. Default: off.
- When on - If your business had already messaged the lead before NZ Leads first received the conversation, the lead’s contact info is not sent to your endpoint. New messages in a conversation don’t send the lead again either.
- When off - Those leads and messages are sent too.
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.
- Needs AI Assistant with Short or Long conversation in Conversation Setup.
- When on, your endpoint gets a lead only once the AI decides the lead is interested, as a request with
"message": "Lead interest confirmed", and again with each new message after that. Turning it on first asks “Let AI decide which leads are sent?” - click Enable to confirm. - It applies to every source that uses this webhook: a source without an AI conversation sends nothing to it while it’s on.
- Can’t be turned on together with Create lead in CRM only when contact info is received or Create only new leads.
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:
message- what happened:New lead created,New message,Lead interest confirmed, orContact info is found in message:followed by the message text.data.lead_id- identifier for the lead. The Lead Reply API uses it to reply to this lead.data.email,data.phone- present when collected.data.postalCode- the lead’s zip code or address, when known.data.firstName,data.lastName- the customer’s name split into first and last.data.tags- holds the source’s name.data.messages- the conversation messages stored on the lead.data.integrations- what NZ Leads has recorded for this lead in other integrations.
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
- Accept
POSTat the configured URL. - Read the
X-Secret-Keyheader and compare it to the secret you copied out of the card. Reject any request where it doesn’t match. - Return a
2xxstatus code within 10 seconds. Any other status is treated as a delivery failure and isn’t retried. For lead requests, the error shows on the integration. - Be idempotent - the same
lead_idmay arrive more than once as a lead updates.
Disconnecting
- For one source - switch the webhook off on that source’s Integrations tab, or untick the source under Where it’s used.
- Everywhere - turn off Enabled, delete the saved URL (expand it → click the delete button → Yes; the webhook URL and secret are cleared), or click Delete integration in the webhook’s window.
Regenerating or deleting the URL invalidates the old secret immediately.
Troubleshooting
- Test webhook endpoint fails - The endpoint didn’t return a
2xxresponse within 10 seconds. Check the URL, that the endpoint is publicly reachable, and that it responds quickly. - The URL isn’t saved - Check that it starts with
http://orhttps://and points to a public server, not a local or private address. - Signature check failing on my side - Make sure you’re comparing against the current secret on the card. If you regenerated the secret, the old one stops working immediately. The test request never carries the header.
- Not receiving anything - Confirm Enable is on and the webhook is on for the source on its Integrations tab. If Create lead in CRM only when contact info is received is on, the lead hasn’t shared phone or email yet, or CRMs isn’t checked in the Contact Info tab. If Create only new leads is on, your business may have messaged the lead before NZ Leads received the conversation. If the AI-interest option is on, the AI hasn’t marked the lead as interested yet.
- The integration shows “Has errors” - Open it and click the warning icon at the top of its Settings to see why requests failed. Errors from the last 7 days are shown.
- NZ Leads is still sending welcome messages after my webhook fires - The webhook doesn’t change NZ Leads’s own messages. To hand the conversation over, turn on Skip welcome message & follow-ups in Conversation Setup.
- I want duplicate protection - Use the
lead_idfield in the payload as an idempotency key.
Questions about the REST Webhook integration? Email support@nzleads.com.