Send conversions to your own systems

Summary

KonversAI can send a message to your own systems every time a visitor starts a chat, verifies their contact details, submits a form, books an appointment, or is handed over to a member of your staff. You give KonversAI an address to post to, and KonversAI signs and sends each event as it happens.

Marketing teams use this to connect ad spend to real business outcomes. If a visitor arrives from an ad, KonversAI includes the ad click ID with the event, so your own reporting can join the conversation back to the campaign that paid for it.

You set this up on the Conversion tracking screen in the KonversAI console, under Settings, in the section Where signals are sent. To send events straight to an analytics or ad platform instead, see Send conversions to Google Analytics 4, Send conversions to ChatGPT Ads, Send conversions to LinkedIn or Send conversions to Google Ads.

Who can do this

You need a role with permission to view and change workspace settings, and conversion tracking must be switched on for your workspace. Contact KonversAI support to switch it on.

Before you start

Conversion tracking is switched off for every workspace until you ask for it. The Conversion tracking item does not appear under Settings until KonversAI enables it. Contact support to have it switched on. Support will talk you through what the events contain before enabling it, because the events carry hashed contact details.

You need an HTTPS address that accepts POST requests and is reachable from the public internet. KonversAI refuses a plain http:// address, and refuses an address that resolves to a private network. A local address on your own machine will not work.

Decide which events you want. KonversAI sends each event at most once per conversation:

• chat_session_started (Conversation started): a visitor starts a chat.
• contact_verified (Contact verified): a visitor verifies an email address or phone number with a code.
• lead_submitted (Lead submitted): a form in the chat is completed, and the form asked for an email address or phone number. A form without a contact field sends no event.
• appointment_booked (Appointment booked): a booking made in the chat is confirmed, either straight away or when your staff approve it. A tentative hold or a booking waiting for approval sends no event.
• handover_to_human (Handed over to a person): a member of your staff sends the first message in the conversation. A visitor asking for a person sends no event until someone answers.

Steps

1. In the KonversAI console, open Settings, then Conversion tracking.
2. Under Where signals are sent, select Connect webhook.
3. In Name, type a label for this destination, such as the name of the system receiving the events.
4. In Endpoint URL, type the HTTPS address that will receive the events.
5. Under Events to send, tick each event you want: Conversation started, Contact verified, Lead submitted, Appointment booked or Handed over to a person.
6. Select Save. KonversAI shows the Signing secret once, on this screen only. Select Copy and store the secret in your own system now. KonversAI cannot show it again.
7. Select Send test event. KonversAI queues one test message and it appears under Recent webhook deliveries within a few seconds.
8. Check that the delivery shows Delivered. If it shows Failed, read the message beside it, fix your endpoint, and select Send test event again.
9. Select Switch on. A new destination is switched off until you do this, and KonversAI records no conversions while nothing on the screen is switched on with an event to send.

To also collect ad click IDs, open Settings, then Widget, then the chat tab, expand Conversion tracking and tick Capture ad click IDs. Click IDs are collected only from visitors who granted marketing consent.

FAQ

What does a KonversAI conversion event contain?

KonversAI posts a JSON body to the Endpoint URL on your Conversion tracking destination. The body carries event_id, event_type, occurred_at, customer_id, session_id, consent_granted, ad_personalization_granted and a data block. event_type is one of chat_session_started, contact_verified, lead_submitted, appointment_booked or handover_to_human.

For a visitor who granted marketing consent, the data block of every event carries the identifiers KonversAI has for the visitor:

• Ad click IDs: gclid, gbraid, wbraid, oppref and li_fat_id, and the ChatGPT Ads browser reference obref.
• Analytics identifiers: ga_client_id, ga_session_ids, fbp and fbc.
• A hashes block with the hashed email address and phone number, when the visitor verified them or typed them into a form: email_lower, email_google, phone_e164 and phone_digits.

A key is left out when KonversAI does not have that identifier. chat_session_started also carries landing_url, the page the visitor arrived on. contact_verified carries contact_channel, which is email or phone. For a visitor who did not grant marketing consent, the data block carries none of these.

What do consent_granted and ad_personalization_granted mean?

consent_granted is true when the visitor granted marketing consent on your website. It answers whether the visitor’s data may be sent to an ad platform at all, which Google calls ad_user_data. ad_personalization_granted is true only when the visitor also allowed their data to be used to personalise ads.

KonversAI never infers ad personalisation from marketing consent. It is true only when your website says so explicitly: by calling KonversaiWidget.setMarketingConsent(tenantKey, true, { adPersonalization: true }), or with data-ad-personalization-consent="granted" next to data-marketing-consent="granted" on the widget script tag. A cookie banner that KonversAI detects on its own never grants it. Forward both values when you send the event on to an ad platform.

How do I check that a message really came from KonversAI?

Every request carries an X-Konversai-Signature header. The header looks like t=1736531200,v1=<hex>. Take the t value, join it to the raw request body with a full stop, and compute an HMAC-SHA256 over that string using the Signing secret from your Conversion tracking destination. Compare the result to the v1 value. Compare the two using a timing-safe comparison, and reject a request whose t is far from the current time. Requests also carry X-Konversai-Topic and X-Konversai-Event, so you can route without reading the body.

I lost the signing secret. How do I get it back?

You cannot read the signing secret again. KonversAI shows it once, when you create the destination. On the Conversion tracking screen, select New signing secret on that destination. KonversAI generates a replacement and shows it once, in the same way. Update your own system straight away: from the moment you generate a new secret, messages are signed with the new one, and your checks against the old secret will fail.

KonversAI sent the same event twice. Is that a bug?

No. KonversAI retries a delivery that fails, so your endpoint can receive the same event more than once. Every event carries an event_id that stays the same across every retry. Store the event_id values you have already handled, and ignore an event whose event_id you have seen before. This is the normal way to handle it.

What happens when my endpoint is down?

KonversAI retries the delivery several times over the following minutes, with a growing wait between attempts. You can watch the attempts under Recent deliveries on the Conversion tracking screen. If a destination fails repeatedly over a long period, KonversAI switches it off and writes the reason on the destination. When you have fixed your endpoint, select Switch on to start sending again.

Does KonversAI send me visitors’ email addresses and phone numbers?

No. Contact details are hashed before they leave KonversAI, and raw personal details never go to your endpoint. Hashed contact details and ad click IDs are included only for visitors who granted marketing consent. For a visitor who did not, KonversAI still sends the event so your session and lead counts stay correct, but the event carries no click IDs and no contact details, and both consent_granted and ad_personalization_granted are false.

How long does KonversAI keep the delivery history?

Recent webhook deliveries on the Conversion tracking screen shows the last 50 attempts. KonversAI deletes the contents of each event after 30 days and keeps the record that the delivery happened. So you can still see that an event was delivered last quarter, but not what was in it.

Why are no conversions showing up at all?

Check three things on the Conversion tracking screen under Settings. First, that a destination is switched on: KonversAI records no conversions while no webhook or platform is switched on with an event to send, and the screen warns you when that is the case. Second, that the destination is subscribed to the event you expect, under Events to send. Third, that the events really are firing — select Send test event to confirm your endpoint accepts a message from KonversAI.

Can I send conversions to more than one system?

Yes. On the Conversion tracking screen, select Connect webhook for each system. Each destination has its own Endpoint URL, its own Signing secret and its own choice under Events to send. KonversAI delivers to each one separately, so a failure at one destination does not affect another.

Can I choose which events a webhook destination gets from the table?

Yes. On the Conversion tracking screen, every webhook destination also appears as a Custom webhook column in the table What to send where. Tick or untick the box in an event’s row to change which events that destination gets. This is the same choice as Events to send on the destination itself, so a change in one place shows in the other.