API & Webhooks

CarBuddy can push real-time event data to your systems via webhooks, and a direct enrollment API is on the roadmap for clients who want programmatic campaign management.

---

Outbound webhooks

CarBuddy fires a webhook to a URL you configure whenever a key event occurs. This lets your CRM, DMS, or internal tooling receive lead data automatically — no manual exports required.

Supported events

Event	When it fires
lead.qualified	A customer has been classified as a qualified lead by the AI
lead.unsubscribed	A customer opted out of outreach
conversation.completed	A customer finished all touchpoints without replying

Payload format

All webhooks send a JSON payload via HTTP POST. Example lead.qualified payload:

{
  "event": "lead.qualified",
  "timestamp": "2025-06-12T10:34:11Z",
  "campaign": {
    "id": "abc123",
    "type": "lost-sales",
    "location": "Ford Anytown"
  },
  "customer": {
    "first_name": "Sarah",
    "last_name": "Jones",
    "email": "sarah.jones@example.com",
    "mobile": "+447700900000"
  },
  "summary": "Customer replied on day 3 asking about PCP options on the Kuga. Confirmed interest in test drive on Friday afternoon.",
  "conversation_url": "https://portal.carbuddyai.com/conversations/xyz789"
}

Setting up a webhook endpoint

To receive webhooks:

1. Build an endpoint on your system that accepts POST requests with Content-Type: application/json
2. Respond with HTTP 200 within 5 seconds — CarBuddy will retry up to 3 times on non-2xx responses
3. Raise a support ticket via the portal support system with your endpoint URL and which events you want to receive

Your account manager will configure the webhook and provide a shared secret for signature verification (see below).

Verifying webhook signatures

Every webhook includes a X-CarBuddy-Signature header containing an HMAC-SHA256 signature of the request body, using your shared secret.

To verify:

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Reject any request where the signature does not match — this protects against spoofed payloads.

---

Direct enrollment API

The direct REST enrollment API is live. Your DMS or CRM can push customer records into a campaign with a single HTTP call — no file uploads required — and pull lead and conversation data back out.

See the Partner API Integration Guide for endpoints, authentication, the full payload spec, and examples. In summary it lets you:

• Enroll customers into campaigns via a single POST request
• Query enrollment status and conversation outcomes
• Have qualified leads delivered to your systems

For scheduled bulk files instead, use SFTP; for manual uploads, use CSV upload.

---

Portal export API

The portal supports CSV exports of all campaign data via the UI. For automated or scheduled exports, raise a support ticket to discuss a data export arrangement with your account manager.

Exports include all recipient records, message history, AI classifications, and conversation outcomes.

---

Questions?

Raise a ticket via the portal support system or contact your account manager to discuss integration options.