Applicable for: organization admins
A webhook is a message your own system receives from NoForm AI, sent to a web address you choose. When a chat visitor becomes a lead, NoForm AI sends that address a POST request holding the lead’s attributes, the AI-written chat summary, the page the chat happened on, and the traffic source. You set this up yourself on the Integrations tab, and no one from the NoForm team needs to add the address for you.
What the webhook sends and when
The webhook fires once per conversation, the first time that conversation qualifies as a lead. A conversation qualifies when the assistant collects one of the attributes you marked as lead-qualifying on the Lead qualification tab of your assistant settings. For background on choosing those attributes, see the article “Configuring Lead Attributes”.
NoForm AI processes newly qualified conversations on a background cycle that runs every minute, so the request normally reaches your endpoint within a minute or two of the visitor sharing the qualifying detail. The webhook covers leads from the chat bubble widget and from the embedded chat.
Where to configure the webhook
Click your organization name in the sidebar of the NoForm AI dashboard, then click “Manage organization”. The dialog that opens has three tabs down the side: Members, Integrations, and Settings. Select Integrations, and you will see two cards: Google Analytics 4 and Webhook. The Webhook card carries the description “Receive a POST request whenever a visitor becomes a lead.”
You need admin access to your organization to open this tab. Members without admin access see the message “You need admin access to view and manage integrations for this organization.” The Integrations tab always configures one specific assistant for your organization. If your organization has more than one assistant, a line above the cards names the one you are configuring.
Fill in the Webhook URL field
Type the full address of your receiving endpoint into the “Webhook URL” field, for example https://example.com/webhook, then click Save. A green status line reading “Webhook settings updated.” confirms the save, along with a “Saved” notification.
The address has to meet these rules:
It must start with
https://. An address starting withhttp://is rejected with the message “Webhook URL must use https://”.It must be a complete, valid web address. Anything else is rejected with “Enter a valid URL”.
It can hold up to 2,048 characters. Longer addresses are rejected with “Webhook URL is too long”.
It must point to a public address on the internet. An address that resolves to a private, internal, or loopback address is rejected with “Webhook URL is not allowed (private or internal address)”.
It must not carry a username or password in the address itself. Those are rejected with “Webhook URL must not contain credentials”.
To turn the webhook off, clear the Webhook URL field and click Save. With no address stored, NoForm AI sends nothing.
Authenticate requests with an API key
The “API key” field is optional and holds up to 512 characters, with the message “API key is too long” if you go over. Whatever you type here travels with every webhook call in the HTTP header Authorization: Bearer <key>, so your endpoint can confirm the request came from NoForm AI and not from someone else who guessed your address.
The field hides the key behind dots as you type. Click the eye icon at the right edge of the field to reveal the stored key and check it against the value your endpoint expects, then click it again to hide the key. On your receiving side, strip the Bearer prefix from the Authorization header, compare what is left against the key you saved here, and reject the request if the two do not match.
Choose a long, random string and keep it secret. To rotate it, paste the new value into the API key field, click Save, and update your endpoint at the same time. If you leave the API key field empty, NoForm AI still sends an Authorization header, and its value is the literal text Bearer undefined.
Send a test event
The “Send test event” button sits next to Save on the Webhook card. It stays disabled until a webhook address is saved, so save your address first, then click the button. NoForm AI posts a sample lead to your endpoint using the same format and the same Authorization header a real lead would use, and waits up to 5 seconds for a reply.
The sample payload carries "test": true alongside the normal fields, so your endpoint can tell a test apart from a real lead. It also uses chatId 0, the sample attributes fullName and email, a sample chat summary that names the test button, and placeholder location values for San Francisco, California.
A status line under the card reports the outcome:
“Your endpoint received the test event (HTTP 200).” means your endpoint answered with a success code.
“Your endpoint returned HTTP 404.” (or another code) means your endpoint answered, but not with a success code. Redirect codes such as 301 and 302 appear here too, because NoForm AI does not follow redirects. Point the Webhook URL at the final address instead.
“Your endpoint didn’t respond within 5 seconds.” means the request reached your endpoint but no reply arrived in time.
“We couldn’t reach your endpoint.” means the address could not be resolved or the connection failed.
What is in the payload
NoForm AI sends Content-Type: application/json and a JSON body with these fields. The Webhook card lists the same field names under “Payload fields” as a quick reference.
Field | Type | What it holds |
| number | Identifier of the conversation |
| string | Identifier of the chatbot that captured the lead |
| string | The visitor’s IP address |
| string | The visitor’s country as a two-letter code, such as |
| string | The visitor’s region or state |
| string | The visitor’s city |
| string | The visitor’s timezone |
| string |
|
| string | The page the conversation took place on |
| string or null | Where the visitor came from |
| date | When the conversation started |
| date | When the conversation qualified as a lead |
| string | The AI-written summary of the conversation |
| object | The lead attributes the assistant collected |
The source value follows a fixed order. A conversation started from a preview or test link always reads Test Chat, no matter what other signals are present. For a real visitor conversation, the value is the utm_source from the landing page address in lowercase when one is present. Without a utm_source, it is the website that referred the visitor, as long as that site is different from your own. When neither applies but the visitor’s browser did report referrer information, the value is Direct. It is null only for the rare case where the widget could not report a referrer at all, such as an older widget version.
The attributes object changes with the attributes you configured for your chatbot. Attribute names arrive in camelCase, so an attribute named “Company Name” becomes companyName.
Example payload
{
"chatId": 12345,
"botId": "64a1b2c3d4e5f6a7b8c9d0e1",
"ipAddress": "203.0.113.42",
"country": "US",
"region": "California",
"city": "San Francisco",
"timezone": "America/Los_Angeles",
"channel": "WIDGET",
"originUrl": "https://example.com/pricing",
"source": "google.com",
"createdAt": "2026-07-20T14:22:00.000Z",
"convertedToLeadAt": "2026-07-20T14:25:33.000Z",
"chatSummary": "Visitor asked about enterprise pricing and requested a demo.",
"attributes": {
"fullName": "Jane Smith",
"email": "[email protected]",
"companyName": "Acme Corp"
}
}
Connect the webhook to an automation tool
If you do not run your own endpoint, an automation tool can give you an address to paste into the Webhook URL field and then route the lead into your CRM, a spreadsheet, or a chat channel. Two step-by-step guides cover this: “Automation Instructions for Zapier.com” and “Automation Instructions for Make.com (Create a Custom Webhook)”. Follow either guide up to the point where it gives you a webhook address, then paste that address into the Webhook URL field on the Integrations tab and click Save instead of sending it to the NoForm team.
To produce a lead the tool can map fields from, click “Send test event” on the Webhook card, or open your chat address in a private browser window and run a conversation in which you share a qualifying detail such as an email address.
Frequently Asked Questions
Does NoForm AI retry a failed webhook?
NoForm AI sends each lead once and does not retry. If your endpoint is down, answers with an error code, or takes longer than 10 seconds to reply, that lead’s webhook is not resent later. Have your endpoint answer with a success code first and do its own processing afterwards, so a slow database or third-party call does not run out the clock.
What happens to my lead if my endpoint is down?
Your lead is safe. Webhook delivery is kept separate from lead processing, so a failed or timed-out webhook does not stop the lead from being saved to your dashboard and does not stop your lead notification email. Only the outbound copy to your system is lost.
Can I use a different webhook address for each chatbot?
The webhook address is stored per chatbot, and the Integrations tab configures the organization’s first assistant. To send leads from several chatbots to different addresses, contact the support team through live chat or at [email protected].
Why does the test event work but real leads never arrive?
The test event and real leads use the same address, headers, and format, so a working test with no real deliveries usually means no conversation has qualified as a lead yet. Open the Lead qualification tab of your assistant settings and confirm that at least one attribute is marked as lead-qualifying, then check your dashboard for leads recorded since you saved the webhook.
Does the payload include everything shown in my dashboard?
The payload carries the chat details, the chat summary, the traffic source, and every lead attribute your assistant collected. For the full list of what NoForm AI records about a chat, see the article “All chat details and lead attributes collected by NoForm”.
Benefits
Your leads reach your CRM, help desk, or team chat within a minute or two, with no exports and no polling.
You configure and change the address yourself on the Integrations tab, without waiting on a support request.
The “Send test event” button proves the connection works before a real lead depends on it.
The API key lets your endpoint reject anything that did not come from NoForm AI.
A broken endpoint never costs you the lead itself, because it still lands in your dashboard and in your notification email.