Skip to main content
Webhooks and API access unlock the full programmatic surface of MerchantAI for teams that need to connect conversation events to external systems, build custom dashboards, or power headless deployments. These capabilities are designed for advanced integration scenarios — piping lead captures into a CRM, triggering support tickets on handover, or building a fully bespoke chat interface — and are available exclusively on the Exchange (Enterprise) plan.
Webhooks and API access are available on the Exchange (Enterprise) plan only. If you are on a Starter or Growth plan and want to explore these features, contact the MerchantAI team to discuss an upgrade.

​
Webhook events

MerchantAI can deliver real-time HTTP POST notifications to your endpoint when key events occur in a conversation. The following events are available:
Fires when a new conversation session is opened — typically the moment a visitor sends their first message. Use this event to create a corresponding record in your CRM or helpdesk, tag the visitor’s session in your analytics platform, or start a real-time monitoring workflow.
Fires when the agent collects a visitor’s contact details (name, email address, or both) during a conversation. This is the most commonly used event for CRM integrations — pipe captured leads directly into your marketing automation tool, sales pipeline, or email platform the moment they are collected.
Fires when the agent determines that a human should take over the conversation. This can happen due to a low-confidence answer, a visitor explicitly asking for a human, or a trigger phrase matching your handover rules. Use this event to create a support ticket, send an internal Slack alert, or open a live-chat session in your helpdesk tool.
Fires each time the agent sends a message to a visitor. Use this event for detailed conversation logging, real-time transcript mirroring to an external system, or building custom analytics pipelines on top of raw message data.

​
Registering a webhook endpoint

1

Open Webhook settings in your dashboard

In the MerchantAI dashboard, navigate to Settings → Webhooks. This page lists all your registered endpoints and lets you add new ones.
2

Enter your endpoint URL

Paste the full HTTPS URL of the server endpoint that should receive webhook payloads. Your endpoint must be publicly reachable and must respond with an HTTP 200 status to acknowledge receipt.
3

Select the events you want to receive

Check the boxes next to the event types you want this endpoint to receive. You can register multiple endpoints and subscribe each one to a different set of events.
4

Save and verify

Click Save. MerchantAI immediately sends a test ping to your endpoint to confirm it is reachable. If the ping succeeds, your endpoint is active and will begin receiving live events. If it fails, check that your server is publicly accessible and returning a 200 response.

​
Webhook payload structure

Every webhook request is an HTTP POST with a JSON body. Below is a representative example for the lead.captured event. 
{
  "event": "lead.captured",
  "timestamp": "2026-06-10T14:32:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "lead_id": "lead_xyz789",
    "name": "Alex Smith",
    "email": "alex@example.com",
    "conversation_id": "conv_def456",
    "source_page": "https://yourstore.com/products/running-shoes"
  }
}
All payloads share the same top-level envelope:
FieldTypeDescription
eventstringThe event type that fired (e.g. lead.captured)
timestampstringISO 8601 UTC timestamp of when the event occurred
workspace_idstringYour MerchantAI workspace identifier
dataobjectEvent-specific payload; fields vary by event type

​
Verifying webhook signatures

Every webhook request from MerchantAI includes an X-MerchantAI-Signature header. This header contains an HMAC-SHA256 signature computed over the raw request body using your webhook secret as the key. Verifying this signature on every incoming request ensures the payload genuinely originated from MerchantAI and has not been tampered with in transit. To verify the signature:
  1. Retrieve your webhook secret from Settings → Webhooks in the dashboard.
  2. Compute HMAC-SHA256(raw_request_body, webhook_secret).
  3. Compare your computed value to the value in the X-MerchantAI-Signature header using a constant-time comparison to prevent timing attacks.
  4. Reject any request where the values do not match.
Most languages have built-in or standard-library support for HMAC-SHA256. Use the raw (unparsed) request body as the input — parsing the JSON first can alter whitespace and invalidate the signature.
Keep your webhook secret confidential. Do not commit it to source control, log it, or expose it in client-side code. If you suspect your secret has been compromised, rotate it immediately from Settings → Webhooks — MerchantAI will begin signing requests with the new secret straight away and you should update your verification logic before the old secret expires.

​
Headless API

In addition to webhooks, the Exchange plan includes access to the MerchantAI programmatic API. The headless API lets you embed MerchantAI into fully custom interfaces — native mobile apps, bespoke web applications, or internal tooling — without using the standard JS widget. Use cases include building a white-labelled chat UI with your own design system, integrating the conversation engine into an existing customer portal, or querying conversation and analytics data programmatically from your own reporting tools. API documentation, base URLs, authentication details, and rate limit information are provided directly by the MerchantAI team as part of Exchange plan onboarding. To request access or get your API credentials, contact support@merchantai.io or reach out via your account manager.