Webhooks

Available on the Scale plan and higher.

Events

• lead.created — a visitor submitted the contact form.
• conversation.handoff — a customer asked to talk to a human.
• message.unanswered — the bot had no relevant content for a question.

Adding one

Go to API & Agents → Webhooks, enter an HTTPS endpoint, tick the events you want, and save. You'll get a signing secret (whsec_…). The last delivery status is shown next to each webhook so you can spot a broken endpoint.

What you receive

POST https://yourapp.com/hooks/mongpt
X-MonGPT-Event: lead.created
X-MonGPT-Timestamp: 1783691750
X-MonGPT-Signature: 69b291806d1023a89d4e414e…
Content-Type: application/json

{
  "event": "lead.created",
  "timestamp": 1783691750,
  "data": {
    "lead_id": "010e19a1-…",
    "session_id": "…",
    "chatbot_id": "9166406d-…",
    "name": "Priya Sharma",
    "email": "[email protected]",
    "phone": null
  }
}

Verifying the signature

Always verify before trusting a payload. The signature is the hex HMAC-SHA256 of `${timestamp}.${rawBody}`, keyed with your signing secret:

import crypto from 'crypto'

function verify(rawBody, headers, secret) {
  const ts  = headers['x-mongpt-timestamp']
  const sig = headers['x-mongpt-signature']
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(sig)
  )
}

Use the raw request body, not a re-serialized object — key order matters. Reject timestamps more than a few minutes old to prevent replay.

Delivery behavior

• Delivered as a fire-and-forget POST; a slow endpoint never slows your customer's chat.
• 10-second timeout. Respond 2xx quickly and do your work asynchronously.
• No automatic retries today — reconcile through the API if you need guarantees.

Scoping

A webhook can listen to all bots or one specific bot. Add several webhooks if different systems care about different events.

Related

Webhooks push events out. To let the bot pull live data during a conversation, see Functions.