Webhooks

Webhooks let you receive real-time HTTP notifications when events happen in your chatbots. Instead of polling the API, Conferbot pushes data to your endpoint as events occur.

How It Works

1. You register a webhook URL and select events to subscribe to.
2. When an event occurs, Conferbot sends a POST request to your URL with a signed JSON payload.
3. Your server verifies the HMAC-SHA256 signature and processes the event.
4. If delivery fails, Conferbot retries up to 3 times with exponential backoff.

Event Types

Subscribe to one or more of the following events:

Payload Format

Webhook payloads are sent as JSON in the POST request body. Each payload includes the event type, resource IDs, and a timestamp.

Headers

Every webhook delivery includes these headers:

Example payload — response.created

{
  "event": "response.created",
  "chatSessionId": "sess_abc123def456",
  "responseId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "botId": "64f8a2b3c1d4e5f6a7b8c9d0",
  "visitorId": "visitor_xyz789",
  "timestamp": "2024-12-15T09:30:00.000Z"
}

Example payload — response.updated

{
  "event": "response.updated",
  "responseId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "botId": "64f8a2b3c1d4e5f6a7b8c9d0",
  "chatSessionId": "sess_abc123def456",
  "timestamp": "2024-12-15T09:35:00.000Z"
}

Signature Verification

Every webhook delivery is signed with your webhook's secret using HMAC-SHA256. Always verify the signature before processing the payload to ensure it came from Conferbot and hasn't been tampered with.

Verification steps

1. Read the raw request body (before JSON parsing).
2. Compute the HMAC-SHA256 hex digest using your webhook secret as the key.
3. Compare it to the x-webhook-signature header value.
4. Use timing-safe comparison to prevent timing attacks.

const crypto = require("crypto");

// Use raw body parser for webhook routes
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const event = req.headers["x-webhook-event"];

  // Compute expected signature
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body) // raw Buffer
    .digest("hex");

  // Timing-safe comparison
  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  // Parse and process the event
  const payload = JSON.parse(req.body);
  console.log(`Received ${event}:`, payload);

  // Respond with 200 to acknowledge receipt
  res.status(200).send("OK");
});

Retries & Failure Handling

If your endpoint doesn't respond with a 2xx status code within 10 seconds, Conferbot considers the delivery failed and retries:

Auto-disable

If a webhook accumulates 10 consecutive failures, it is automatically set to failed status and stops receiving events. You can reactivate it from the dashboard or API after fixing the issue.

Delivery logs

Every delivery attempt is logged with status code, response time, and error details. Logs are retained for 30 days. View them in the Workspace → Webhooks tab or via the Webhooks API.

Testing Webhooks

Use a service like webhook.site or RequestBin to test webhooks without setting up your own server:

1. Go to webhook.site and copy your unique URL.
2. Create a webhook in your Conferbot dashboard using that URL.
3. Trigger an event (e.g., submit a chatbot response).
4. Check webhook.site to see the payload and headers.

Next Steps