LeadFloAgent/Docs

Webhooks

Receive real-time HTTP POST events when leads are captured or conversations end.

Webhooks

LeadFloAgent can send an HTTP POST request to your server whenever a significant event occurs — such as a visitor submitting the lead form or a conversation ending. Use webhooks to push leads into your CRM, trigger follow-up sequences in your email marketing platform, or log data to your own systems.

Setup

  1. Go to Dashboard → your website → Settings → Webhooks.
  2. Enter your endpoint URL. It must be an HTTPS URL publicly accessible from the internet.
  3. Optionally enter a webhook secret (recommended — see Verifying the Secret below).
  4. Click Save. LeadFloAgent will begin sending events to your endpoint immediately.

Your server must respond with a 2xx HTTP status code within 5 seconds. If your processing takes longer than 5 seconds, respond immediately with 200 OK and handle the work asynchronously.

Events

EventTrigger
visitor_createdLead form submitted — visitor name and email captured
conversation_endedChat conversation closed by visitor or timed out

Example Payload — visitor_created

This event fires when a visitor submits the lead form. This is the primary event to listen for when integrating with a CRM.

{
  "event": "visitor_created",
  "timestamp": "2025-03-01T14:22:00.000Z",
  "websiteId": "web_abc123",
  "data": {
    "visitor": {
      "id": "vis_xyz",
      "name": "Sarah Johnson",
      "email": "sarah@example.com",
      "phone": "+1 555 123 4567",
      "country": "US",
      "city": "Austin",
      "referrer": "https://zillow.com",
      "firstSeenAt": "2025-03-01T14:20:00.000Z",
      "qualityScore": 88,
      "urgencyScore": 72,
      "customFields": {
        "intent": "Buy",
        "timeFrame": "1-3 mo"
      }
    }
  }
}

Payload Fields

FieldTypeDescription
eventstringEvent type identifier
timestampISO 8601UTC timestamp of the event
websiteIdstringYour LeadFloAgent website ID
data.visitor.idstringUnique visitor identifier
data.visitor.namestringFull name from lead form
data.visitor.emailstringEmail address from lead form
data.visitor.phonestringPhone number (if provided)
data.visitor.countrystringCountry inferred from IP (ISO 3166-1 alpha-2)
data.visitor.citystringCity inferred from IP
data.visitor.referrerstringPage the visitor came from
data.visitor.firstSeenAtISO 8601When the visitor first opened the widget
data.visitor.qualityScoreinteger (0–100)Lead completeness and seriousness score
data.visitor.urgencyScoreinteger (0–100)How soon the visitor intends to act
data.visitor.customFields.intentstringBuy / Sell / Rent
data.visitor.customFields.timeFramestringASAP / 1–3 mo / 3–6 mo / 6+ mo

Example Payload — conversation_ended

{
  "event": "conversation_ended",
  "timestamp": "2025-03-01T14:28:00.000Z",
  "websiteId": "web_abc123",
  "data": {
    "conversationId": "conv_789",
    "visitorId": "vis_xyz",
    "leadCaptured": true,
    "messageCount": 12,
    "durationSeconds": 487
  }
}

Verifying the Secret

When you configure a webhook secret, LeadFloAgent sends it in the x-webhook-secret request header with every POST. Verify this value on your server before processing the payload to confirm the request is genuinely from LeadFloAgent.

// Node.js / Express example
app.post("/leadflo-webhook", express.json(), (req, res) => {
  const provided = req.headers["x-webhook-secret"];

  if (provided !== process.env.LEADFLO_WEBHOOK_SECRET) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  const { event, data } = req.body;

  if (event === "visitor_created") {
    // Push the lead to your CRM
    crm.createContact({
      name: data.visitor.name,
      email: data.visitor.email,
      phone: data.visitor.phone,
      intent: data.visitor.customFields.intent,
      timeFrame: data.visitor.customFields.timeFrame,
      urgencyScore: data.visitor.urgencyScore,
    });
  }

  // Respond quickly — do heavy processing asynchronously
  res.sendStatus(200);
});

Always compare the secret using a constant-time comparison to prevent timing attacks. In Node.js, use crypto.timingSafeEqual for production implementations.

Common CRM Integrations

Webhooks work with any HTTP-capable integration platform. Common patterns:

  • Zapier or Make (formerly Integromat): Use the webhook trigger to catch visitor_created events, then push to HubSpot, Follow Up Boss, Salesforce, or any CRM that has a Zapier integration.
  • Direct API: Parse the webhook payload on your own server and call your CRM's API directly.
  • Slack notification: Forward lead details to a Slack channel for immediate team visibility.

Important Notes

  • LeadFloAgent does not retry failed webhook deliveries. If your endpoint is down or returns a non-2xx status, that event is not retried. Design your endpoint to be highly available, or use a queueing intermediary.
  • Your endpoint must respond within 5 seconds. Process data asynchronously if your logic takes longer.
  • Test your webhook by submitting a test lead via your chat widget and confirming your endpoint receives the visitor_created event.
  • Webhook delivery is included on Brokerage plans. Check your plan details at Dashboard → Billing.
← PreviousWidget Integration