Webhook

Webhook delivery (bot → your middleware)

​

Landbot POSTs this payload to the webhook URL set on the APIchat channel, once per message the bot or a human agent sends. The customer's own messages, pushed with POST /send/{customer_token}/, don't come back here.

There is no Authorization header, so put a secret in the URL or accept requests through a gateway you control. Answer any 2xx within 60 seconds. Any other status, 4xx included, is retried about 5, 10, 15, 20 and 25 seconds later; timeouts and connection errors aren't. There is no message ID: use customer.token with the message timestamp to spot a retry. See Webhooks.

Body·

required
application/json

APIchat webhook delivery body. Unlike Platform, customer/channel/agent are TOP-LEVEL, not nested per message. Always exactly one entry in messages (no batching).

  • agent
    Type:
    required

    Who emitted the message — shared across the whole envelope (APIchat has no per-message sender). Conditional shape: bot envelopes carry only { id, type }; human-agent envelopes also carry { name, email } from the agent's Landbot account. Switch on type for attribution.

    Properties: 4
  • channel
    Type:
    required

    The APIchat channel. Note: there is NO channel.type field — its absence is the reliable discriminator that you're reading an APIchat (not Platform) envelope.

    Properties: 2
  • customer
    Type:
    required

    The customer this conversation belongs to: Landbot identifiers plus the customer's Field bag. Custom Fields set by a Set-Field block appear as ADDITIONAL top-level keys (only on webhooks emitted after the block runs) and may be type-mangled — treat values as strings unless guaranteed otherwise. No Platform-style metadata (agent_id/is_external/country/url/archived).

    Properties: 7
  • messages
    Type:
    required

Responses

  • 200

    Acknowledged. Any 2xx works; the body is ignored. Any other status is retried.

Request Example for postmessage
{
  "messages": [
    {
      "type": "text",
      "timestamp": 1,
      "message": ""
    }
  ],
  "customer": {
    "id": 1,
    "token": "",
    "register_date": 1,
    "name": null,
    "phone": null,
    "email": null,
    "additionalProperty": "anything"
  },
  "channel": {
    "id": 1,
    "name": ""
  },
  "agent": {
    "id": 1,
    "type": "bot",
    "name": "",
    "email": ""
  }
}
No Body

Acknowledged. Any 2xx works; the body is ignored. Any other status is retried.

Previous
Webhooks
Next
Error