WebhooksPro

Webhooks send a JSON message to a URL of your choice whenever something happens in the chat, so you can pass leads, escalations and sales to your other tools.

Webhooks are a Pro feature. The receiving URL can be your own server or a “catch webhook” address from an automation service such as Zapier, Make or n8n, which then forwards the data to your CRM or e-mail tool.

Set up a webhook

  1. Open AI Assistant → Settings → Integrations and find Webhook Integration.
  2. Paste the receiving address in Webhook URL. It must start with http:// or https://; use HTTPS.
  3. Optionally enter a Secret Key. With a secret, each message carries a signature your endpoint can check (see below).
  4. Under Events to Send, tick the events you want. If you tick none, all events are sent.
  5. Click Send Test Ping. It uses the URL and secret currently in the fields, even before you save, and reports whether your endpoint answered with a success status.
  6. Turn on Enable Webhooks and click Save Webhook Settings.

Events

Each event is listed with the fields of its data object.

  • conversation_started: a new conversation was saved. Fields: session_id, page_url, page_type.
  • conversation_escalated: a customer submitted the escalation form. Fields: session_id, name, email, phone.
  • lead_captured: an e-mail address was captured. Fields: email, name, session_id, source, cart_value.
  • purchase_after_chat: an order was placed after a chat. Fields: order_id, total, currency, email, coupon_used.
  • satisfaction_rated: a customer rated the conversation. Fields: session_id, rating (1 to 5).
  • discount_offered: the assistant offered a coupon. Fields: session_id, coupon_code, type, amount, level.

The test ping uses the event name test_ping with a message field.

Payload

Every webhook is an HTTP POST with the header Content-Type: application/json and this body:

{
  "event": "lead_captured",
  "timestamp": "2026-01-15T10:30:00+00:00",
  "site_url": "https://yourstore.com",
  "site_name": "Your Store",
  "data": {
    "email": "customer@example.com",
    "name": "Alex",
    "session_id": "3f1c9a52-6f0e-4b7a-9d0e-2c1b7a5e8d44",
    "source": "chat",
    "cart_value": 42.5
  },
  "signature": "9b2f…e41c"
}
  • event: one of the event names above.
  • timestamp: when the event was sent, in ISO 8601 format (UTC).
  • site_url and site_name: the store that sent it.
  • data: the event’s fields.
  • signature: present only when a secret key is set.

Verify the signature

When you set a secret key, the plugin computes an HMAC-SHA256 of the JSON-encoded data object with your secret, and puts the hexadecimal result in the signature field of the body. It is not sent as an HTTP header. To verify a message, recompute the value and compare:

<?php
$secret = 'your-secret-key';

$raw  = file_get_contents( 'php://input' );
$body = json_decode( $raw, true );

if ( ! is_array( $body ) || ! isset( $body['data'], $body['signature'] ) ) {
    http_response_code( 400 );
    exit;
}

// The signature covers the "data" object only, encoded as JSON.
$expected = hash_hmac( 'sha256', json_encode( $body['data'] ), $secret );

if ( ! hash_equals( $expected, $body['signature'] ) ) {
    http_response_code( 401 );
    exit;
}

// Verified. Handle $body['event'] and $body['data'] here.
http_response_code( 200 );

The signature is calculated over the output of PHP’s json_encode() with default options, which escapes forward slashes (\/) and non-ASCII characters (\uXXXX). In another language, make sure you re-encode data the same way and keep the fields in the order received, or the values will not match. The Integrations screen also has a Copy verification example button.

Delivery and troubleshooting

  • Events are sent once, in the background, without waiting for your endpoint’s answer and without retrying. Answer quickly and do slow work afterwards. If you must not miss an event, receive it with a service that queues incoming webhooks.
  • Delivery History on the Integrations screen lists recent attempts with their event, status and endpoint. Customer data from the payload is not stored there. Because real events don’t wait for an answer, they show as “Sent, not confirmed”; only the test ping records your endpoint’s HTTP status.
  • The endpoint must have a valid SSL certificate when you use HTTPS.
  • If your Pro subscription ends, webhooks stop being sent. Your settings are kept. See Licence and activation.

Building on the same site? The same six events are available as WordPress action hooks, listed in the REST API reference.

Still stuck?

Check the troubleshooting guide, or contact support and tell us what you tried.