Webhooks

Webhooks

Suppabot can send a real-time HTTP POST request to your server when specific events occur. Use webhooks to sync leads to your CRM, trigger automations in Zapier or Make, or update your own database without polling.

---

Setup

1. Go to Dashboard → your website → Settings → Webhooks.
2. Enter your endpoint URL. It must be publicly accessible over HTTPS.
3. Optionally enter a Webhook Secret — a string you define that Suppabot will include in every request header for verification.
4. Click Save.

Your endpoint begins receiving events immediately.

---

Events

Event	When it fires
visitor_created	A new visitor submits the lead form
conversation_ended	A chat conversation is closed

---

Payload format

All events share a common envelope structure:

{
  "event": "<event_name>",
  "timestamp": "<ISO 8601 datetime>",
  "websiteId": "<website ID>",
  "data": { }
}

visitor_created

{
  "event": "visitor_created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "websiteId": "web_abc123",
  "data": {
    "visitor": {
      "id": "vis_xyz",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+1 555 000 0000",
      "company": "Acme Corp",
      "jobTitle": "Marketing Manager",
      "country": "US",
      "city": "New York",
      "referrer": "https://google.com",
      "firstSeenAt": "2025-01-15T10:29:55.000Z",
      "lastSeenAt": "2025-01-15T10:30:00.000Z",
      "interests": ["pricing", "enterprise"],
      "qualityScore": 82,
      "urgencyScore": 65
    }
  }
}

conversation_ended

{
  "event": "conversation_ended",
  "timestamp": "2025-01-15T10:45:00.000Z",
  "websiteId": "web_abc123",
  "data": {
    "conversation": {
      "id": "conv_123",
      "startedAt": "2025-01-15T10:30:00.000Z",
      "endedAt": "2025-01-15T10:45:00.000Z",
      "outcome": "lead_captured",
      "messageCount": 8,
      "firstMessage": "Hi, I'm interested in your enterprise plan"
    }
  }
}

Possible outcome values: lead_captured, handoff_requested, resolved, abandoned.

---

Verifying requests

If you set a webhook secret during setup, Suppabot includes it in the X-Webhook-Secret header of every request. Verify it in your handler before processing the payload.

Node.js / Express

app.post("/webhook", express.json(), (req, res) => {
  const secret = req.headers["x-webhook-secret"];
  if (secret !== process.env.SUPPABOT_WEBHOOK_SECRET) {
    return res.status(401).send("Unauthorized");
  }

  const { event, data } = req.body;

  switch (event) {
    case "visitor_created":
      // sync to CRM, send welcome email, etc.
      console.log("New lead:", data.visitor.email);
      break;
    case "conversation_ended":
      // log to analytics, trigger follow-up, etc.
      console.log("Conversation ended:", data.conversation.outcome);
      break;
  }

  res.status(200).send("OK");
});

Python / Flask

from flask import Flask, request
import os

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    secret = request.headers.get("X-Webhook-Secret")
    if secret != os.environ["SUPPABOT_WEBHOOK_SECRET"]:
        return "Unauthorized", 401

    payload = request.json
    event = payload.get("event")
    data = payload.get("data")

    if event == "visitor_created":
        visitor = data["visitor"]
        # sync to CRM, etc.
        print(f"New lead: {visitor['email']}")
    elif event == "conversation_ended":
        conversation = data["conversation"]
        print(f"Conversation ended: {conversation['outcome']}")

    return "OK", 200

---

Response requirements

Your endpoint must respond with HTTP 200 within 10 seconds. Suppabot considers any other response code (or a timeout) a delivery failure.

Retries: Suppabot does not retry failed webhook deliveries. If your endpoint is unavailable at the time of the event, the delivery is lost. Build idempotency into your handler using the event payload's timestamp and entity IDs so that duplicate deliveries (if they ever occur) are handled safely.

---

Testing

During development, use one of the following to inspect payloads without deploying your server:

• webhook.site — generates a temporary HTTPS URL that logs incoming requests in your browser.
• ngrok — creates a public HTTPS tunnel to your localhost server.

Paste the temporary URL as your webhook endpoint in Suppabot, trigger a test conversation, and inspect the payload in the tool's interface.

---

Removing a webhook

To stop receiving webhook events, go to Dashboard → your website → Settings → Webhooks, clear the endpoint URL, and click Save.