API & Webhook Integration

Complete API reference for integrating Clay webhooks, platform monitoring, and direct lead ingestion

Integration Overview

Superkabe provides three primary integration points:

1. Clay Webhook — Receive enriched leads from Clay tables
2. Platform Webhooks — Monitor bounce/sent events from Smartlead, EmailBison, and Instantly
3. Direct Ingestion API — Programmatic lead submission
4. Campaign Resolution API — Automate stalled campaign recovery

1. Clay Webhook Integration

Send enriched leads from Clay directly to Superkabe for campaign routing and protection.

Endpoint

POST https://api.superkabe.com/api/ingest/clay

Authentication

Header: x-organization-id

Your organization ID from Superkabe dashboard (Settings → API Keys)

Request Body

{
  "email": "john.doe@example.com",          // Required
  "persona": "VP Engineering",              // Optional, defaults to "General"
  "lead_score": 85,                         // Optional, defaults to 50
  "firstName": "John",                      // Optional
  "lastName": "Doe",                        // Optional
  "company": "Acme Corp",                   // Optional
  "campaignId": "campaign_xyz"    // Optional (for direct assignment)
}

💡 Flexible Field Mapping

Clay webhook supports case-insensitive field lookup:

• email, E-mail, or work email
• persona, job title, title, or role
• lead score, score, or lead_score

Response

{
  "message": "Lead ingested successfully",
  "leadId": "lead_abc123",
  "assignedCampaignId": "campaign_xyz" // null if no routing rule matched
}

2. Smartlead Webhook Integration

Smartlead sends real-time bounce and delivery events to Superkabe for monitoring.

Endpoint

POST https://api.superkabe.com/api/monitor/smartlead-webhook

Setup in Smartlead

1. Navigate to Smartlead → Settings → Webhooks
2. Add webhook URL: https://api.superkabe.com/api/monitor/smartlead-webhook
3. Add header: x-organization-id: YOUR_ORG_ID
4. Select events: email_sent, email_bounce, delivery_failure
5. (Optional) Configure webhook secret in Superkabe Settings for signature validation

Supported Event Types

Smartlead Event	Superkabe Action
email_sent	Increment mailbox send count
email_bounce	Record hard bounce, check thresholds
hard_bounce	Record hard bounce, check thresholds
soft_bounce	Log soft bounce (no threshold trigger)
delivery_failure	Record failure, update risk score

Expected Payload Format

{
  "event": "email_bounce",
  "mailbox_id": "mailbox_abc123",      // or "mailbox": {...}
  "campaign_id": "campaign_xyz",
  "email": "recipient@example.com",
  "timestamp": "2026-02-08T12:00:00Z"
}

3. Direct Ingestion API

Programmatically submit leads to Superkabe from your own systems.

Endpoint

POST https://api.superkabe.com/api/ingest

Authentication

Header: x-organization-id

Your organization ID from Superkabe dashboard

Request Body

{
  "email": "jane.smith@company.com",   // Required
  "persona": "CTO",                    // Required
  "lead_score": 90,                    // Required (0-100)
  "source": "api"                      // Optional
}

Response

{
  "message": "Lead ingested successfully",
  "leadId": "lead_def456",
  "assignedCampaignId": "campaign_123"
}

Error Codes

Status	Reason	Solution
400	Missing required fields	Check request body for email, persona, lead_score
401	Missing organization context	Add `x-organization-id` header
409	Duplicate webhook event	Event already processed (idempotency)
500	Internal server error	Retry with exponential backoff

Best Practices

1. Idempotency: All webhook endpoints use idempotency keys to prevent duplicate processing
2. Retries: Implement exponential backoff for 5xx errors
3. Webhook Security: Configure webhook secrets in Smartlead and Superkabe for signature validation
4. Field Mapping: Use consistent field names in Clay to avoid case-sensitivity issues
5. Monitoring: Check Superkabe audit logs to verify successful webhook delivery

Testing Your Integration

cURL Example - Clay Webhook

curl -X POST https://api.superkabe.com/api/ingest/clay \
  -H "Content-Type: application/json" \
  -H "x-organization-id: YOUR_ORG_ID" \
  -d '{
    "email": "test@example.com",
    "persona": "VP Sales",
    "lead_score": 75,
    "firstName": "Test",
    "lastName": "User"
  }'

cURL Example - Smartlead Webhook Test

curl -X POST https://api.superkabe.com/api/monitor/smartlead-webhook \
  -H "Content-Type: application/json" \
  -H "x-organization-id: YOUR_ORG_ID" \
  -d '{
    "event": "email_bounce",
    "mailbox_id": "mailbox_test_123",
    "campaign_id": "campaign_abc",
    "email": "bounced@example.com"
  }'