Inbound Webhooks Guide

Inbound webhooks let another system send caller data to Moja AI before routing, or update an existing call record after the fact. Choose the right type — pre‑call enrichment and post‑call updates use different matching rules and payloads.

What you can do:

Send caller metadata pre‑call for routing, attribution, and downstream handoff
Update buyer/call revenue on completed calls
Add, replace, or remove custom tags on calls
Update supported call fields and tags together

Choose a webhook type

call_data → /call-data: store caller metadata for a matching incoming call
update_revenue → /update-revenue: update buyer/call revenue
update_tags → /update-tags: add, replace, or remove call tags
update_fields → /update-fields: update supported call fields and tags together

Type names contain underscores; endpoint paths contain hyphens. Copy the generated URL from the saved configuration rather than substituting the type name into a URL.

Create the incoming webhook

Open Webhooks → Incoming → Create.
Enter a Name and choose Type. Add a description if useful.
For Call Data, set Lifespan (seconds). The current create form defaults to 3600 seconds (1 hour). Choose a window appropriate for how early your caller data arrives.
For the update types, set Caller ID Match Days between 1 and 7; the current form defaults to 7. This controls phone‑number fallback matching, not exact Call Log ID matching.
Click Create, then copy the generated Webhook URL from the saved configuration.

For call_data, also:

Attach the configuration to the receiving campaign under the campaign’s Incoming Webhooks setting
Create matching Custom Tags for every extra field you want to apply to calls (for example lead_source, zip_code, publisher_call_id)

Creating the webhook alone does not complete pre‑call enrichment — campaign attachment and custom‑tag setup are required.

For the update types, treat the auth key as organization‑scoped access. Do not rely on a campaign attachment as a restriction on which call records a sender can update.

Authentication and request format

Keep moja_auth_key on the URL query string, including for POST requests:

https://webhooks.moja.cloud/call-data?moja_auth_key=YOUR_AUTH_KEY

Use POST with a JSON body for structured payloads and all batch updates. Set Content-Type: application/json.

GET is available for single‑call requests; nested field and tag operations use bracket notation. URL‑encode query values, especially the + in an E.164 phone number as %2B.

Missing or invalid authentication returns 401.

Send pre‑call data with call_data

Send caller_id and your agreed custom fields before the call arrives whenever possible:

{
  "caller_id": "+12125551234",
  "lead_source": "google_ads",
  "zip_code": "33139",
  "publisher_call_id": "publisher-reference-10001"
}

Notes:

caller_id must match the inbound caller number Moja sees; phone_number is not a substitute. E.164 is preferred.
Create Custom Tags such as lead_source, zip_code, and publisher_call_id before testing.
A success response confirms receipt and storage, not that a call has already been enriched.

Make the data available before routing

The webhook and phone call are separate requests. If arrival timing is uncertain, add a Wait For Pre Call Webhooks node before the Routing Plan (or any nodes that depend on the data) in the campaign call flow. Verify the matched custom tags on the call and map them into downstream requests or routing logic.

Identify an existing call for updates

Prefer call_log_id when exactly one call should change.

Alternatively, send phone_number to match the caller ANI (not the dialed campaign number). Every matching call in the configured Caller ID Match Days window can be affected. Batch arrays cannot be combined with phone_number.

Update revenue

POST to /update-revenue with call_log_id (or phone), revenue_paid_out as a number, and optional transaction_id. See the Revenue Postback Endpoint Guide.

Update tags

POST to /update-tags with at least one of add or remove.

Update fields and tags together

POST to /update-fields. Put call‑record updates inside fields and tag operations inside tags:

{
  "call_log_id": "YOUR_CALL_LOG_ID",
  "fields": {
    "converted": true,
    "revenue_paid_out": 25.50,
    "reason": "Qualified lead"
  },
  "tags": {
    "add": [{"lead_quality": "high"}],
    "remove": ["pending_review"]
  },
  "transaction_id": "field-update-10001"
}

Supported field keys include: converted, call_converted_at, revenue_paid_out, publisher_paid_out, reason, no_payout_reason.

Optional top‑level require_connected_duration: true (threshold at least 1 second). If the call has no connected duration, the request is rejected when this flag is set.

Batch updates and partial success

update_revenue, update_tags, and update_fields accept a POST JSON array of up to 50 Call Log IDs. call_data does not.

HTTP 200 does not guarantee every operation succeeded — always read success, partial_success, call_log_ids, and any failed_call_log_ids/failures fields in the response.

Retries and idempotency

Use a stable transaction_id. A completed duplicate can return the stored response; an in‑flight duplicate can return 409.

For 429 and other transient failures, retry with bounded exponential backoff. Do not retry a completed partial‑success under a new transaction_id without reconciling first.

Test before going live

Verify:

Type, endpoint, auth on query string, and content‑type
For call_data, that custom tags exist, the webhook is attached to the campaign, and a Wait For Pre Call Webhooks fallback is in place when timing is uncertain
For updates, that you can update a known Call Log ID and see the result in Reporting

Need help?

support@mojaai.com