# LeadPilot API — Inbound Webhook Ingestion

**Document Version:** 1.0.0 (Phase 11)  
**Base URL:** `/api/v1`

---

## 1. Webhook Endpoint

```http
POST /api/v1/webhooks/leads/{endpoint_uuid}
```

This endpoint receives raw lead events from external platforms (e.g. Typeform, custom websites, CRM bridges, form builders).

---

## 2. Security & Signature Verification

If a secret is configured on the `WebhookSource`:
- The client must include one of the following HMAC-SHA256 signature headers:
  - `X-LeadPilot-Signature`
  - `X-Hub-Signature-256`
  - `X-Signature`
- The signature is calculated as `hash_hmac('sha256', raw_request_body, secret)`.

---

## 3. Example Request

```http
POST /api/v1/webhooks/leads/9c836a99-bcf8-4d51-a9f7-64150ec8e7b9
Content-Type: application/json
X-LeadPilot-Signature: 5d41402abc4b2a76b9719d911017c592...

{
  "respondent_first_name": "Marcus",
  "respondent_last_name": "Aurelius",
  "respondent_email": "marcus@rome.gov",
  "org_name": "Roman Advisory",
  "answers_summary": "Inquiry regarding strategic consulting."
}
```

---

## 4. Response

```json
{
  "success": true,
  "data": {
    "lead_id": "9cb5a045-8fe1-4c48-8df0-202d6fae3b3a",
    "is_duplicate": false,
    "followup_enrolled": true,
    "status": "ingested"
  },
  "message": "Lead successfully captured."
}
```

---

## 5. Webhook Logs

All inbound webhook deliveries are permanently logged in `webhook_logs` with the raw payload, processing status (`processed` / `failed`), and error message (if any).