Webhooks

Webhooks let you send real-time notifications to external services whenever specific events happen in your Knock Knock App account. This is useful for connecting with custom tools, internal systems, or services not covered by our other integrations.

Creating a Webhook

To create a new webhook:

1. Go to Integrations in the sidebar.
2. Find Webhooks and click Manage.
3. Click Add Webhook.
4. Enter a name to identify this webhook.
5. Enter the URL where you want events to be sent.
6. Select the events you want to listen for.
7. Click Save to create the webhook.

tip

Give your webhooks descriptive names like "New Lead to Internal CRM" or "Chat Ended to Analytics" so you can easily identify their purpose later.

Available Events

You can choose which events trigger your webhook. The available events include:

Event	When It Fires
New Session	A visitor starts a new session on your site.
Visitor Identified	An anonymous visitor becomes identified — by a form, chat, call, the graph, or a click on a tracked ?kk= email link.
New Lead	A visitor shares contact details through chat, a call, or a form. Carries where the lead came from.
Lead Score Updated	A visitor's lead score changes.
Chat Ended	A chat conversation is closed or completed.
New Meeting Booked	A visitor books a meeting.
Meeting Rescheduled	A booked meeting is moved to a new time.
Meeting Cancelled	A booked meeting is cancelled.
Call Ended	A phone or widget call finishes (channel is phone or web).

A click on a tracked ?kk= link — from an Agent K email, your own CRM templates, or a ManyReach campaign — fires Visitor Identified with the contact the link belongs to (contact.source is kk_token), once per visit and never for bots. That lets you alert your own CRM or inbox when a campaign recipient lands on your site.

You can select one or more events per webhook. Each selected event will send a notification to your specified URL when it occurs. The same catalogue powers the Zapier triggers.

note

You can create multiple webhooks that listen for different events, or a single webhook that listens for all events. Choose the approach that best fits your workflow.

Payload Format

Webhook and Zapier payloads send a curated, documented set of session fields rather than raw internal records. Signed new_lead webhooks embed the session document in the same curated shape.

:::warning Action needed for existing integrations If your automation referenced undocumented internal fields, update it to use the documented fields — the in-app documentation (the Documentation tab on the Webhooks screen) shows the exact current payloads. :::

Where the Lead Came From

Every New Lead payload carries lead_source: the page and product the lead came from, how they reached your site, and whether they converted in a chat, a call, or a form. It's built at the moment the details are captured.

Field	What It Contains
lead_type	chat, call, or form — what the visitor was doing when they gave their details. Details shared during a live call count as call, even if typed into the chat panel.
page_url	The page the visitor was on when they gave their details.
page_title	That page's title, when the widget could read it.
product	Derived from the page: the title without the site-name suffix ("Solar Panels | Acme" → "Solar Panels"), or the last URL segment when there's no title.
chat_start_url / call_start_url	The page the chat or call started on — whichever matches lead_type.
landing_page_url	The first page of the visit.
traffic_source	How they reached your site: source (e.g. "Google Ads"), source_category, the UTM fields, gclid, and referrer. Only keys with a value are present.
captured_at	When the details were captured.

URLs are origin + path only — query strings are stripped; UTMs and the Google Ads click ID are reported separately under traffic_source. traffic_source.gclid is the click ID to send to Google Ads offline-conversion import. It always reflects the visitor's latest ad click, and the same value is kept current on user_session.traffic_source.gclid.

Links to the Chat, Call and Recording

New Lead payloads also carry links — direct links into your dashboard so your team can jump from the alert to the conversation:

Field	When It's Present
chat_url	Chat leads — opens the conversation in Chats.
call_url	Call leads — opens the call on the Calls page. Only included when the call is listed there (a call that never connected has no link).
session_recording_url	When the visit has a session recording — opens it in Recorded Sessions.

The links use your dashboard's address (your agency's portal domain if you're on a white-labeled portal) and need a login to open. Any link that doesn't apply is left out.

The same details are written as a note on the contact in LeadConnector and HubSpot, and into the Lead's Description in Salesforce.

Post-Call Webhook Payload

Call Ended payloads include the results of the post-call analysis alongside the call details:

• call_sentiment — the caller's sentiment for the call: positive, neutral, or negative.
• transcript_text — a plain-text transcript in Speaker: text form, sent alongside the structured transcript array. Use it when your automation just needs readable text.
• recording_url — a signed public streaming link to the call recording, valid for about a year. No login is needed, so your automations can fetch the audio directly.

Delivery Timing

The post-call webhook waits for the post-call analysis (including the summary) before firing, so payloads arrive complete. If the analysis never arrives, a fallback delivery fires within a few minutes without the analysis fields. Either way, exactly one delivery is sent per call.

New User Identified Event

The New User Identified event fires when an anonymous visitor becomes identified during a session — whether through Knock Knock's own identity graph or through enrichment. It fires at most once per session, and never for visitors who were already known before the session started.

The payload includes:

Field	What It Contains
user_session_id	The session in which the visitor was identified.
contact	name, email, phone, and source of the identity.
company	The identified visitor's company name.
ip	The visitor's IP address.
initial_page_visit	The first page the visitor landed on.
identified_at	When the identification happened.

Testing Webhooks

After creating a webhook, you can test it to make sure everything is working:

1. Go to your webhook settings.
2. Click the Test button next to the webhook you want to verify.
3. A sample event will be sent to your URL.
4. Check your receiving service to confirm the test event arrived.

info

Test events are clearly marked as test data so you can distinguish them from real events. Use testing to verify your setup before going live.

Managing Webhooks

From the webhooks management page, you can:

• Edit -- Change the URL, name, or selected events for an existing webhook.
• Disable -- Temporarily stop a webhook without deleting it.
• Delete -- Permanently remove a webhook you no longer need.
• View logs -- See recent delivery attempts and their status. Retried deliveries are marked attempt N.

Retries and Auto-Disable

A delivery that fails — a timeout, a 5xx, a 408 or 429 — is retried up to four times with increasing waits (from about a minute, doubling, capped at 30 minutes). Any other 4xx counts as a permanent rejection and isn't retried. Every attempt appears in the logs.

If five deliveries in a row fail after all their retries, the webhook is switched off and shows an amber auto-disabled badge next to its status (hover it for the reason). Fix the endpoint, then re-enable the webhook.

warning

Deleting a webhook is permanent. If you might need it again later, consider disabling it instead.

Next Steps

• Explore Zapier for a no-code alternative to webhooks
• Prefer pulling data on your own schedule? Use the Lead API
• Running an agency with your own platform? See the Platform API
• Connect Slack for team notifications
• Review all available integrations