Webhooks & callbacks

“Webhook” means different things in CXGear depending on who is calling whom. This page separates the three patterns teams meet most often:

Table ingest webhooks — your CRM calls CXGear to add rows
Channel / WhatsApp webhooks — Meta (or another provider) calls CXGear about messages
OAuth callbacks — the browser returns to CXGear after you connect an account

Getting the public API URL wrong breaks all three.

Public API URL matters

CXGear must advertise a stable HTTPS base URL for anything an external system calls. In deployment that is PUBLIC_API_URL (for example https://api.cxgear.ai).

Use	Example
Ingest webhook path	`https://api.cxgear.ai/api/v1/public/data-tables/ingest/{token}`
WhatsApp OAuth callback	`https://api.cxgear.ai/api/v1/channels/whatsapp/oauth/callback`

If PUBLIC_API_URL is localhost in production, providers cannot reach you. See Deployment notes.

1. Table ingest webhooks

Direction: CRM / middleware → CXGear

Purpose: Append rows to a data table automatically.

Each data table can expose:

A URL containing an ingest token
Optional CRM-specific setup notes in the product UI

Your system sends HTTP POST requests with a records array. CXGear appends rows when columns match the table schema.

Screenshot needed

Ingest webhook panel showing URL and token (token partially masked if possible).

Where: Data tables → Ingest webhook

Save as: src/assets/screenshots/32-ingest-webhook.png

Good practice

Set metadata fields so only useful columns enter spinners.
Keep the ingest token secret (rotate if it leaks).
Send the same column names the table already uses.
After rows land, run or trigger a published spinner.

Organization API keys can also ingest via /public/ingest when you prefer one key for many tables. See Public ingest & trigger and Ingest webhooks.

2. WhatsApp and messaging webhooks

Direction: Meta (or SMS/email provider) → CXGear

Purpose: Deliver inbound messages, delivery statuses, and related events so channels and conversations stay up to date.

You configure these in the provider console (for example Meta for WhatsApp), pointing at CXGear’s API host — not the web app.

Typical setup steps:

Connect WhatsApp under Integrations in CXGear.
Complete Meta OAuth (see below).
Ensure the webhook URL and verify token match what CXGear expects for your deployment.
Subscribe only to the event types CXGear documents for WhatsApp.

Screenshot needed

WhatsApp / channel connection screen in Integrations.

Where: Integrations → WhatsApp

Save as: src/assets/screenshots/39-whatsapp-webhook-setup.png

If inbound messages never appear:

Confirm the provider can reach PUBLIC_API_URL over HTTPS
Confirm the app is live (or you are a Meta tester in development mode)
Check API logs for webhook verification failures

See WhatsApp (Meta).

3. OAuth callbacks

Direction: Browser → CXGear API after the user approves access at the provider

Purpose: Finish connecting WhatsApp (and other OAuth-based integrations) without pasting long-lived tokens by hand.

For WhatsApp, the redirect URI must match exactly, including path:

https://YOUR_API_HOST/api/v1/channels/whatsapp/oauth/callback

That host must be the same value as PUBLIC_API_URL. A mismatch is the most common OAuth failure.

Tips

Do not invent extra scopes — CXGear requests the WhatsApp scopes it needs
In Meta development mode, only app admins, developers, and testers can complete login
After success, you should land back in CXGear with the channel connected

How these relate to API keys

Mechanism	Credential
Org ingest / trigger API	`Authorization: Bearer cxg_…`
Per-table ingest webhook	Token in URL path
Provider webhooks	Provider signature / verify token (not your org API key)
OAuth callback	Browser session + provider authorization code

You usually do not put an org API key on a Meta webhook URL.

Success looks like

CRM rows appear in the data table within seconds of an event
WhatsApp inbound messages show up in CXGear
OAuth completes without “redirect URI mismatch”
Tokens and keys are stored securely and rotated when people leave

Common problems

Problem	Likely cause	What to do
Ingest 404	Wrong or rotated token	Copy URL again from Data tables
SCHEMA_MISMATCH	Payload columns differ	Align with table schema
OAuth redirect error	`PUBLIC_API_URL` ≠ Meta app setting	Make them identical
Provider cannot reach CXGear	Firewall or HTTP-only URL	Use public HTTPS API host
Webhooks work in staging only	Production URL not updated	Update provider config and env