Skip to main content

Lead Delivery

Lead Delivery sends a minimized lead payload to a configured destination. It is a separate outbound contract from Event Hooks and Workflow Webhook Actions. A delivery attempt records transport outcome; it does not mean the destination accepted the lead into a CRM or that a conversion occurred.

Subscription setup​

Configure a protected destination, signing secret, event/mapping policy, and optional Workflow handoff through the Workspace-authorized Lead Delivery surface. The current validator accepts http or https and rejects localhost/private/restricted resolutions; do not infer an HTTPS-only contract until the applicable policy enforces it.

POST /api/leads/<YOUR_LEAD_ID>/delivery-attempts HTTP/1.1
Authorization: Bearer <YOUR_WORKSPACE_SESSION>
Content-Type: application/json

{
  "subscriptionId": "<YOUR_SUBSCRIPTION_ID>",
  "idempotencyKey": "<YOUR_ATTEMPT_OPERATION_ID>"
}

This route creates or returns an attempt for an existing subscription; subscription configuration is owned by the authenticated product surface and is not represented here as a separate public stable route. Secrets are returned or rotated only according to the copy-once/masked lifecycle and must be stored server-side. Do not put a Lead Delivery secret in a Widget, browser bundle, URL, or log.

The worker currently sends the lead.ready-for-delivery event. The authority contract also defines lead.captured, lead.delivered, and lead.delivery-failed for the broader lead lifecycle; do not assume every lifecycle event is emitted by the current transport. It must not send raw provider payloads, unnecessary identity fields, or provider credentials. Lead qualification and conversion are separate domain outcomes.

Attempts and outcome​

Each lead delivery has an independent attempt with attempt number, status, response classification, next retry time, and correlation ID. One destination’s failure does not rewrite another destination’s outcome. A retryable network/429/5xx result follows bounded backoff; a validation, policy, authentication, or terminal destination failure is recorded as terminal and may disable the subscription. An authorized retry uses POST /api/leads/retries/{attemptId} with a new idempotency key.

Use delivery-attempt history to diagnose the transport. A successful 2xx is delivery acceptance by the HTTP endpoint only; it is not CRM success, qualification, attribution, or conversion.