Webhook API Spec — Lead Buyer & Publisher Integration

Authentication

All API requests use Bearer token authentication. Your API token is issued when your application is approved. Include it in every request:

Authorization: Bearer dl_live_xxxxxxxxxxxxxxxxxxxx

All issued tokens are production tokens (dl_live_ prefix). Contact Dreamy@dreamyleads.com to request sandbox access for integration testing.

Buyer Webhook — Receiving Leads

As a buyer, you provide an HTTPS endpoint that we POST lead data to when you win an auction. Your endpoint must:

Accept HTTPS POST requests
Return HTTP 200 within 10 seconds
Return a JSON body with "status": "accepted" or "status": "rejected"

We send the following headers on every buyer webhook delivery:

POST https://your-crm.com/leads/inbound
Content-Type: application/json

HMAC-SHA256 request signing is available for enterprise integrations. Contact Dreamy@dreamyleads.com to enable webhook signatures on your account.

Publisher Endpoint — Submitting Leads

As a publisher, you POST leads to our inbound endpoint. The ping-tree responds in real time with an accept or reject decision and a bid price.

POST https://api.dreamyleads.com/webhook/lead
Authorization: Bearer dl_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Payload Schema

All fields marked * are required. Vertical-specific fields are marked with their vertical.

{
  "vertical": "insurance",     // * insurance | mortgage | solar | debt
  "first_name": "Maria",         // *
  "last_name": "G.",              // *
  "email": "m@example.com",     // *
  "phone": "+18135550100",       // * E.164 format
  "zip": "33601",              // * 5-digit US ZIP
  "tcpa_timestamp": "2026-04-27T09:14:22Z",  // * ISO 8601
  "tcpa_text": "By submitting...",  // * verbatim consent
  "tcpa_url": "https://...",       // * page URL

  // Insurance-specific
  "coverage_type": "auto",
  "vehicle_year": 2021,
  "homeowner": true,

  // Mortgage-specific
  "loan_purpose": "purchase",
  "loan_amount": 385000,
  "credit_range": "good",

  // Solar-specific
  "monthly_electric_bill": 285,
  "roof_type": "shingle",

  // Debt-specific
  "debt_amount": "15000–25000",
  "debt_type": "credit_card"
}

Response Format & Status Codes

All responses are JSON. A successful accepted lead returns:

{
  "status": "accepted",
  "bid_amount": 47.50,
  "lead_id": "ld_0000001a",
  "quality_score": 82,
  "quality_grade": "A"
}

A rejected lead returns:

{
  "status": "rejected",
  "reason": "no_buyer_accepted",
  "quality_score": 58,
  "lead_id": "ld_0000001b"
}

HTTP Status	Meaning	Action
`200 accepted`	Lead qualified and bid placed — buyer matched	Record lead_id for tracking
`200 rejected`	Lead received but rejected (low score, no buyer match, or filter mismatch)	No charge; log reason and continue
`400`	Malformed request (missing required fields)	Fix payload; do not retry
`401`	Invalid or missing Bearer token	Check token; do not retry
`422`	TCPA consent fields missing or invalid	Fix tcpa_timestamp, tcpa_text, tcpa_url; do not retry
`5xx`	Server error	Retry with exponential backoff: 1s, 2s, 4s, 8s

Error Handling & Retries

For 5xx responses, retry with exponential backoff: 1s, 2s, 4s, 8s, then abandon. Never retry 4xx responses — they indicate a fixable problem with your request, not a transient server issue.

Code Samples

cURL

curl -X POST https://api.dreamyleads.com/webhook/lead \
  -H "Authorization: Bearer dl_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"vertical":"insurance","first_name":"Maria","last_name":"G.","email":"m@example.com","phone":"+18135550100","zip":"33601","tcpa_timestamp":"2026-04-27T09:14:22Z","tcpa_text":"By submitting...","tcpa_url":"https://seo.example.com/page"}'

Node.js

const res = await fetch('https://api.dreamyleads.com/webhook/lead', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    vertical: 'insurance',
    first_name: 'Maria', last_name: 'G.',
    email: 'm@example.com', phone: '+18135550100', zip: '33601',
    tcpa_timestamp: new Date().toISOString(),
    tcpa_text: 'By submitting this form you consent...',
    tcpa_url: window.location.href,
  }),
});
const data = await res.json();
// accepted: { status: 'accepted', bid_amount: 47.50, lead_id: 'ld_0000001a', quality_score: 82, quality_grade: 'A' }
// rejected: { status: 'rejected', reason: 'no_buyer_accepted', quality_score: 58, lead_id: 'ld_0000001b' }

Python

import requests, os
resp = requests.post(
    'https://api.dreamyleads.com/webhook/lead',
    headers={'Authorization': f"Bearer {os.environ['DL_API_KEY']}"},
    json={
        'vertical': 'insurance',
        'first_name': 'Maria', 'last_name': 'G.',
        'email': 'm@example.com', 'phone': '+18135550100', 'zip': '33601',
        'tcpa_timestamp': '2026-04-27T09:14:22Z',
        'tcpa_text': 'By submitting this form you consent...',
        'tcpa_url': 'https://seo.example.com/page',
    },
    timeout=15
)
print(resp.json())
# accepted: {'status': 'accepted', 'bid_amount': 47.5, 'lead_id': 'ld_0000001a', 'quality_score': 82, 'quality_grade': 'A'}
# rejected: {'status': 'rejected', 'reason': 'no_buyer_accepted', 'quality_score': 58, 'lead_id': 'ld_0000001b'}

Need help integrating?

Email Dreamy@dreamyleads.com with your lead_id and the response you received. We respond within 24 hours on business days.

Webhook Integration Spec — Dreamy Leads API