Skip to main content

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​

EventWhen it fires
lead.qualifiedA customer has been classified as a qualified lead by the AI
lead.unsubscribedA customer opted out of outreach
conversation.completedA 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​

Coming Soon

Direct REST API enrollment is on our roadmap. This will allow your DMS or CRM to push customer records directly via HTTP — no file uploads required.

If you have a specific use case or timeline requirement, contact us to discuss.

Planned capability​

The enrollment API will let you:

  • Enroll individual customers into campaigns via a single POST request
  • Query enrollment status and conversation outcomes
  • Suppress or unenroll customers programmatically

In the meantime, use SFTP for automated batch enrollment or CSV upload for manual uploads.

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.