> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MerchantAI Webhooks and API Access — Exchange Plan

> Use MerchantAI webhooks and the headless API to build real-time integrations, custom CRMs, and programmatic workflows on the Exchange plan.

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.

<Note>
  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.
</Note>

## 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:

<Accordion title="conversation.created">
  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.
</Accordion>

<Accordion title="lead.captured">
  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.
</Accordion>

<Accordion title="handover.triggered">
  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.
</Accordion>

<Accordion title="message.sent">
  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.
</Accordion>

## Registering a webhook endpoint

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Webhook payload structure

Every webhook request is an HTTP POST with a JSON body. Below is a representative example for the `lead.captured` event.

```json theme={null}
{
  "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:

| Field          | Type   | Description                                       |
| -------------- | ------ | ------------------------------------------------- |
| `event`        | string | The event type that fired (e.g. `lead.captured`)  |
| `timestamp`    | string | ISO 8601 UTC timestamp of when the event occurred |
| `workspace_id` | string | Your MerchantAI workspace identifier              |
| `data`         | object | Event-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.

<Warning>
  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.
</Warning>

## 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](mailto:support@merchantai.io) or reach out via your account manager.