InstaChime webhook capture API

When to use the capture API

Use the capture endpoint for custom website forms, landing pages, ad-platform bridges, no-code tools, and server-side form handlers.

Send the lead as soon as the source receives it. InstaChime stores the raw payload, normalizes common fields, checks for duplicates, runs routing, and starts alert delivery.

Endpoint and headers

POST JSON, form-urlencoded, or plain text payloads to the capture endpoint. For new work, use JSON unless the source platform cannot send JSON. If your capture workflow uses a shared secret, send it in the `x-instachime-secret` header.

Copy the endpoint Generate the shared secret Place the secret in the source

curl -X POST https://instachime.com/api/webhooks/capture \
  -H "content-type: application/json" \
  -H "x-instachime-secret: YOUR_SHARED_SECRET" \
  -d '{
    "source": "website_form",
    "full_name": "Jamie Lee",
    "email": "jamie@example.com",
    "phone": "+15555550123",
    "message": "I need pricing today",
    "utm_source": "google",
    "utm_campaign": "emergency-demo"
  }'

Recommended fields

`source` or `source_platform`: lead origin such as `google_ads`, `meta_lead_ads`, `website_form`, or `zapier`.
`full_name`, `first_name`, `last_name`: contact name fields. Send both if available.
`email` and `phone`: primary dedupe, routing, and follow-up fields. Use E.164 format for phone when possible.
`company`, `company_domain`, `job_title`: optional context for B2B routing and scoring.
`message`, `service`, `product`, `preferred_contact_method`, `preferred_contact_time`: useful routing and response context.
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `gclid`, `fbclid`: attribution fields for reporting.

Verification

Capture request returns 200 with a lead ID.
Lead appears in `/app` without refreshing the dashboard.
Lead has normalized email, phone, source, campaign, and raw fields.
A repeated request with the same source ID or contact fingerprint does not create a duplicate operational lead.
Configured alert channels and CRM webhooks record delivery rows in `/integrations`.

Integration launch checklist Google Ads webhook test steps

Copy the capture endpoint

Use this exact URL anywhere a source platform, connector, server-side form handler, or automation tool asks for the InstaChime webhook URL.

Paste the full URL, including `https://` and `/api/webhooks/capture`.
Use HTTP POST. Do not use GET.
Use HTTPS only. If a tool asks for a method, select POST.
Do not change the path to `/webhooks/capture`; that path is not the public capture URL.

https://instachime.com/api/webhooks/capture

Generate the shared secret

The shared secret is a private value used to reject lead submissions from unknown senders. Generate it once, save it in a password manager or internal secret vault, and paste the exact same value into the lead source or bridge.

Use a password manager password generator, 1Password/Bitwarden secret generator, OpenSSL, or PowerShell cryptographic random bytes.
Use at least 32 random characters. Do not use a brand name, campaign name, email address, phone number, date, or reused password.
Copy the generated value without leading spaces, trailing spaces, or line breaks.
Save a label such as `InstaChime capture secret - production` beside the value so the team knows what it protects.
Give the value only to the people or systems that configure lead delivery.
Never place the shared secret in public browser JavaScript, public Git repositories, screenshots, or public documentation.
If your InstaChime workspace is managed by another administrator, ask that administrator for the active capture secret before configuring an external source.

macOS or Linux:
openssl rand -base64 32

Windows PowerShell:
$bytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
[Convert]::ToBase64String($bytes)

Place the secret in the source

Google Ads Lead Form Assets: paste the shared secret into the Google webhook key field.
Website forms: keep the secret on the server-side form handler and send it as the `x-instachime-secret` header.
Meta, TikTok, and LinkedIn bridges: keep the secret in the bridge or middleware, then send it as the `x-instachime-secret` header after the bridge retrieves the full lead fields.
Zapier or Make source-side webhooks: use a webhook/custom request step that can include the `x-instachime-secret` header.
Do not put the secret into a hidden form field, public landing-page HTML, or client-side tag manager variable.

Google Ads setup Website forms setup

Rotate the shared secret

Create a new random secret and save it before changing any live source.
Schedule the rotation when someone can immediately send a test lead from every connected source.
Update each source platform, bridge, or server-side sender with the new value.
Update the active InstaChime capture secret through the administrator who manages the workspace.
Send one test lead from every source and confirm each request returns 200.
If any source returns 401 or 403, pause that source and compare the exact copied value before turning live traffic back on.

Build the sender request

Send every lead to `https://instachime.com/api/webhooks/capture` with HTTP POST.
Use `content-type: application/json` for new integrations. Use form-urlencoded only when the source cannot send JSON.
Include `x-instachime-secret: YOUR_SHARED_SECRET` when a shared secret is configured.
Send a unique source identifier when the vendor gives one, for example `lead_id`, `leadgen_id`, `tiktok_lead_id`, `linkedin_response_urn`, or `form_submission_id`.
Send raw attribution fields exactly as received from the source, including UTM fields, click IDs, ad IDs, campaign IDs, form IDs, and timestamps.
Send consent fields if the source captures them, for example privacy policy acceptance, SMS consent, email consent, or custom disclaimer responses.

Normalize names and contact fields

If the source gives `first_name` and `last_name`, send both fields.
If the source gives only one name field, send it as `full_name`.
Send phone numbers in E.164 format when the source provides country information, for example `+15555550123`.
Send email in lowercase if your bridge can normalize it safely.
Do not drop unknown fields. Put anything you do not map into the JSON body so InstaChime can retain it in raw fields.

Handle response codes

Treat HTTP 200 from InstaChime as accepted.
If the response includes a lead ID, save it in the source run log or middleware log.
Treat 401 or 403 as a secret/configuration problem and stop retrying until the secret is fixed.
Treat 400 as a payload-shape problem and inspect the request body.
Retry 5xx responses with exponential backoff because they can represent a temporary service problem.

Troubleshooting

Lead does not appear: confirm the source sent to `/api/webhooks/capture`, not `/webhooks/capture`.
Secret failure: compare the exact shared-secret value configured in the source with the protected InstaChime value; watch for spaces copied before or after the secret.
Phone missing: confirm the source uses `phone`, `phone_number`, `PHONE_NUMBER`, or a clearly named custom field.
Duplicates: confirm the source identifier is stable and sent on every retry.
Source attribution missing: confirm `source`, `source_platform`, `campaign`, and UTM fields are being sent by the bridge.