GoodInbound

Lead Status Webhooks

Keep your CRM, reporting, and ad integrations in sync when a submission becomes an accepted lead, is withdrawn, or is restored. GoodInbound delivers these changes through a workflow with the lead_conversion_changed trigger.

Submission → Screening → Accepted lead → accept event
                              ↓
                    Later reclassification → withdraw event
                              ↓
                         Restored lead → accept event, higher revision

Receive conversion changes by webhook#

Create a workflow with the lead_conversion_changed trigger and a webhook step. Keep its body empty to send the full workflow context, including conversion and available attribution.

You can configure this through the dashboard or the management API. Set PROJECT_ID and GOODINBOUND_API_KEY, then create the workflow:

curl --request POST "https://goodinbound.com/api/projects/$PROJECT_ID/workflows" \
  --header "Authorization: Bearer $GOODINBOUND_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Lead conversion reporting","trigger":"lead_conversion_changed"}'

Save workflow.id from the response as WORKFLOW_ID. Add your receiving URL:

curl --request POST \
  "https://goodinbound.com/api/projects/$PROJECT_ID/workflows/$WORKFLOW_ID/steps" \
  --header "Authorization: Bearer $GOODINBOUND_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "sortOrder": 0,
    "type": "webhook",
    "config": {
      "url": "https://example.com/webhooks/goodinbound",
      "method": "POST"
    }
  }'

Replace the example URL with your working receiver. Configure signature verification, then activate the workflow:

curl --request PUT \
  "https://goodinbound.com/api/projects/$PROJECT_ID/workflows/$WORKFLOW_ID" \
  --header "Authorization: Bearer $GOODINBOUND_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"status":"active"}'

The conversion portion of a webhook looks like this:

{
  "conversion": {
    "eventId": "68a297e2-c7b3-4228-8906-5c7b8165a9cd",
    "conversionId": "c9ff8d11-5cb5-47aa-834c-549f91897f4c",
    "revision": 2,
    "operation": "withdraw",
    "eligible": false,
    "occurredAt": "2026-10-14T10:00:00.000Z"
  }
}

conversionId stays the same through accept → withdraw → accept. Each change has its own eventId and a higher revision. Process a change once, ignore older revisions after newer ones, and update the existing conversion rather than creating a new lead when it is restored. Ignore payloads with conversion.test: true in production reporting.

Verify and acknowledge deliveries#

Copy the workflow's Signing secret from the webhook step in the dashboard. Secret retrieval is dashboard-only; it is not exposed to REST API keys.

Each request includes:

GoodInbound-Delivery: <workflow-run-id>.<step-index>
GoodInbound-Signature: t=<unix-seconds>,v1=<hex-signature>

Verify the signature against HMAC-SHA256(secret, timestamp + "." + rawRequestBody) using a constant-time comparison. Verify before parsing or modifying the body, and reject timestamps outside a short tolerance such as five minutes. Store the delivery ID to recognize retries, durably accept the event, then return a 2xx response. Non-2xx responses are retried with backoff for about 24 hours.

Your receiver owns any downstream ad-platform upload or adjustment. Receiving operation: "withdraw" is not proof that an external platform removed a conversion.

Use the conversion decision#

Both the Lead Screening API and Form Backend API return these fields. Example, showing the conversion portion only:

{
  "screening": { "state": "final", "revision": 1 },
  "conversion": {
    "eligible": true,
    "reason": "accepted_lead",
    "event_id": "c9ff8d11-5cb5-47aa-834c-549f91897f4c",
    "occurred_at": "2026-10-14T09:00:00.000Z"
  }
}

Report a lead only when conversion.eligible === true. A 200 response, completed form, or action: "allow" alone is not sufficient. Pending, review, spam, pitch, bot, unscreened, and failed results must not trigger an accepted-lead conversion.

Field Use
screening.state pending, final, not_screened, or failed
screening.revision Version of the screening decision
conversion.eligible Whether this result may be reported as an accepted lead
conversion.reason accepted_lead, pending, not_a_lead, screened_out, not_screened, or failed
conversion.event_id Stable submission identity for conversion deduplication
conversion.occurred_at Event timestamp when eligible; otherwise null
result_token Returned for pending screening so the browser can check again

Resolve pending decisions#

Call GET /api/v1/leadscreen/results/:result_token without an API key. It returns screening and conversion, without submitted personal data. Tokens expire after 15 minutes. Use increasing delays, stop after a final result, and stop on 404. Withhold the conversion if you cannot obtain an eligible result.

The script performs a short polling sequence automatically. Use server-side workflows for decisions that finish after the visitor leaves or is later reviewed by your team.

Reporting and limits#

Use Analytics → Lead quality and Paid traffic to inspect screening outcomes and attribution. These dashboard reports are not public API-key endpoints. The public aggregate analytics API supports:

curl "https://goodinbound.com/api/projects/$PROJECT_ID/analytics/overview?period=30d" \
  --header "Authorization: Bearer $GOODINBOUND_API_KEY"

period accepts 7d, 30d, 90d, or custom with start and end. Aggregate form and booking funnels describe visitor activity; do not interpret every funnel completion as a screened, accepted lead. Use conversion webhooks as the source for acceptance and withdrawal changes in your own reporting.

Detailed analytics requires Pro. Workflow runs use the workspace allowance: 250/month on Free and 5,000/month on Pro. Management API calls are limited to 120/minute per key. On 400 check request fields; on 401/403 check credentials, project, and access; on 429 inspect the returned rate or quota details. For platform delivery errors, inspect the workflow run and connection before retrying.

For browser tags and native Meta or TikTok delivery, see Conversion Tracking.