Receive website chat messages with a webhook

Messages, new chats, forms and handoffs — as they happen.

POST/v1/webhook-endpointswebhooks:manage

Add a webhook endpoint

Request

curl -X POST "https://api.iotabot.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://crm.acme.com/iotabot",
  "channels": [
    "website"
  ],
  "events": [
    "message.received",
    "conversation.created",
    "form.submitted",
    "conversation.handoff_requested"
  ]
}'

Response · 201

{
  "data": {
    "id": "6a4bb0…",
    "object": "webhook_endpoint",
    "url": "https://crm.acme.com/iotabot",
    "status": "active",
    "secret": "whsec_…",
    "verification": {
      "verified": true,
      "reason": null
    }
  }
}

WEBHOOKmessage.received

{
  "id": "evt_6a4ba40bc3f1a2b3c4d5e750",
  "object": "event",
  "type": "message.received",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T09:15:02.881Z",
  "livemode": true,
  "channel": "website",
  "website_id": "6a4b3fbbe291bce5bf701c5c",
  "data": {
    "message": {
      "id": "6a4b9e5dc3f1a2b3c4d5e701",
      "object": "message",
      "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
      "channel": "website",
      "direction": "inbound",
      "sender": {
        "type": "visitor",
        "name": null
      },
      "type": "text",
      "text": "Hi, where is my order #1042?",
      "html": null,
      "html_raw": null,
      "attachments": [],
      "status": "received",
      "delivery": null,
      "created_at": "2026-10-01T09:15:02.881Z"
    },
    "conversation": {
      "id": "6a4b9e21c3f1a2b3c4d5e6f7",
      "object": "conversation",
      "channel": "website",
      "website_id": "6a4b3fbbe291bce5bf701c5c",
      "status": "open",
      "mode": "ai",
      "subject": null,
      "contact": {
        "name": "Priya Sharma",
        "email": "priya@example.com",
        "phone": null,
        "external_id": "user_8421"
      },
      "assigned_agent_id": null,
      "tags": [],
      "integration_replies": true,
      "message_count": 3,
      "created_at": "2026-10-01T09:12:44.120Z",
      "last_message_at": "2026-10-01T09:15:02.881Z"
    }
  }
}

WEBHOOKform.submitted

{
  "id": "evt_6a4ba40bc3f1a2b3c4d5e750",
  "object": "event",
  "type": "form.submitted",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T09:15:02.881Z",
  "livemode": true,
  "channel": "website",
  "website_id": "6a4b3fbbe291bce5bf701c5c",
  "data": {
    "submission_id": "fs_9x2…",
    "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "form": {
      "id": "6a4b77…",
      "name": "Book a demo",
      "slug": "book-a-demo"
    },
    "fields": {
      "name": "Priya Sharma",
      "email": "priya@example.com"
    },
    "submitted_at": "2026-10-01T09:20:00.000Z"
  }
}