Webhooks

Webhooks move call data between Moja and your systems in real time. They come in two directions, and the direction determines almost everything else about how you configure them.

Direction	Portal location	What it does
Outgoing	Webhooks → Outgoing	Moja sends an HTTP request to your endpoint when a call event fires
Incoming	Webhooks → Incoming	You send an HTTP request to Moja to pass caller data, update revenue, update tags, or update fields

Caution

Creating a webhook does not start sending traffic. After you save an outgoing webhook, attach it to each campaign under Campaign → Outgoing webhooks, or to a target or RTB formula. To deliver the same call to more than one receiver, see Send call data to more than one outbound webhook.

Outgoing webhooks

Events

Each outgoing webhook triggers on one event type. These are the common ones. The complete and current list is in Webhooks → Outgoing in the dashboard when you create or edit a webhook — treat the dashboard as authoritative if it disagrees with this table.

Event	Fires when
call.incoming	A caller dials a tracking number and the platform begins processing
call.connected	The call connects to a target
call.hangup	Either party ends the call
call.failure	The call cannot be connected to a target — busy, no answer, or error
call.completed	Post-call processing finishes, including conversion evaluation and logging
call.converted	The call meets the conversion criteria. Fires after hangup
call.on_5_secs_mark	Connected duration reaches 5 seconds
call.on_15_secs_mark	Connected duration reaches 15 seconds
call.on_30_secs_mark	Connected duration reaches 30 seconds
call.on_45_secs_mark	Connected duration reaches 45 seconds
call.on_60_secs_mark	Connected duration reaches 60 seconds

Payload shape

There is no fixed Moja payload. You define the entire request — URL, HTTP method, headers, and body — as a template, and Moja substitutes [TAG_NAME] placeholders with real call data at dispatch time.

Supported methods: GET, POST, PUT, PATCH, DELETE. Supported body formats: JSON (application/json) and form data (application/x-www-form-urlencoded).

Template

{
  "call_id": "[CALL_ID]",
  "caller": "[CALLER_ID]",
  "campaign": "[CAMPAIGN_NAME]",
  "duration": "[DURATION]",
  "converted": "[CONVERTED]",
  "revenue": "[REVENUE_PAID_OUT]",
  "tags": {
    "source": "[UTM_SOURCE]",
    "state": "[CALLER_STATE]"
  }
}

Delivered payload

{
  "call_id": "call_abc123def456",
  "caller": "+13105559876",
  "campaign": "Medicare Leads Q1",
  "duration": "145",
  "converted": "true",
  "revenue": "35.00",
  "tags": {
    "source": "google_ads",
    "state": "CA"
  }
}

Placeholders work in the URL and query string too:

https://your-api.com/webhook?call_id=[CALL_ID]&campaign=[CAMPAIGN_ID]

Configuration fields

Field	Tier	Notes
Endpoint URL	Required	Use HTTPS
Event type	Required	One event per webhook. Create several webhooks to cover several events
HTTP method	Required	GET, POST, PUT, PATCH, or DELETE
Body template	Required for methods with a body	Uses [TAG_NAME] placeholders
Body format	Required	JSON or form data
Custom headers	Recommended	Where you put your own Authorization header or a shared secret
Campaign or target attachment	Required to receive traffic	Attach under Campaign → Outgoing webhooks, or on a target or RTB formula

Tags

Tags are the placeholder vocabulary. The full, current list appears in the dashboard when you build the template; the groups below are the ones most integrations use.

Call identification — [CALL_ID], [CALL_SID], [INBOUND_CALL_ID], [ORG_ID], [FROM], [TO], [CALLER_ID], [CALLER_ID_NO_PLUS], [CALLER_ID_NUMERIC], [CALLER_ZIP], [CALLER_STATE], [STATE], [ZIP_CODE], [ORIGINAL_STATE], [ORIGINAL_ZIP_CODE]

Campaign and publisher — [CAMPAIGN_ID], [CAMPAIGN_NAME], [PUBLISHER_ID], [PUBLISHER_NAME], [PUBLISHER_NUMBER], [PAYOUT], [PAYOUT_NUMERIC]

Target and buyer — [TARGET_ID], [TARGET_NAME], [TARGET_TYPE], [BUYER_ID], [BUYER_NAME], [TARGET_PAYOUT], [PUBLISHER_PAYOUT]

Conversion and revenue — [CONVERTED], [REVENUE_PAID_OUT], [PUBLISHER_PAID_OUT], [DURATION], [INBOUND_DURATION], [OUTBOUND_DURATION], [CALL_TERMINATION_BY], [CALL_CONVERTED_AT], [EVENT_TIMESTAMP], [CONFIGURED_PUBLISHER_PAYOUT], [CONFIGURED_BUYER_REVENUE], [OVERWRITTEN_BUYER_REVENUE], and the _NUMERIC variants of the configured amounts

Attribution — populated for calls that came through DNI: [GCLID], [FBCLID], [UTM_SOURCE], [UTM_MEDIUM], [UTM_CAMPAIGN], [UTM_CONTENT], [UTM_TERM], [KEYWORD], [VISITOR_ID], [LANDING_PAGE], [LANDING_PAGE_DOMAIN], [LANDING_PAGE_PATH], [REFERRER], [VISITOR_CITY], [VISITOR_STATE], [VISITOR_ZIP], [VISITOR_COUNTRY], [VISITOR_IP], [VISITOR_BROWSER]

Custom tags — any custom tag you define is available as its key in uppercase. A tag with key lead_type becomes [LEAD_TYPE].

Caution

Not every tag is populated on every event. Conversion tags such as [CONVERTED] and [REVENUE_PAID_OUT] have no value on an early event like call.incoming. When a tag is unavailable for the event that fired, the raw placeholder text is sent instead of a value — your receiver will literally get the string [CONVERTED]. Handle that case rather than assuming a type.

Incoming webhooks

Four types, each with its own endpoint and request shape. Create them under Webhooks → Incoming; saving generates the URL and auth key.

Type	Endpoint	Purpose
call_data	/call-data	Pass caller metadata before or during routing
update_revenue	/update-revenue	Update revenue and conversion data on a call
update_tags	/update-tags	Add or remove custom tags on a call
update_fields	/update-fields	Update several call record fields in one request

All four authenticate with moja_auth_key as a query parameter:

POST https://webhooks.moja.cloud/{webhook_type}?moja_auth_key={your_auth_key}

Requests without a valid key return 401 Unauthorized.

call_data

Sends caller metadata ahead of the call. Moja matches it to an incoming call by caller ID, and applies any fields that correspond to custom tags you have defined.

curl -X POST 'https://webhooks.moja.cloud/call-data?moja_auth_key=YOUR_AUTH_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "caller_id": "+13105559876",
    "lead_source": "google_ads",
    "ad_campaign": "medicare_q1",
    "landing_page": "medicare-info"
  }'

Field	Tier	Type	Notes
caller_id	Required	string	Matched against incoming calls
transaction_id	Recommended	string	Idempotency key
Any other field	Optional	string	Stored with the request; applied as a tag if it matches a defined custom tag

The match lookback window is configurable per webhook. The default is 15 days.

Note

Inbound webhook tags and request parameters are normalized before routing-plan resolution and call-flow execution, so variable and tag nodes in a call flow can read them. Since March 2026, tag extraction processes all request headers, not only X- prefixed ones. If you previously relied on non-X- headers being excluded, review your tag configuration.

update_revenue

Documented in full on the postbacks page, which is the same endpoint viewed as a conversion-reporting workflow.

update_tags and update_fields

TODO

Document the request bodies, field lists, and responses for update_tags and update_fields. The current help center names both types and their endpoints but does not specify their payloads. Do not guess field names here.

Retries and idempotency

Inbound. Send a stable transaction_id with each logical event. When the same organization and transaction_id arrive again after a completed attempt, Moja returns the original stored response rather than applying the request a second time. A request still in flight with that ID may return 409 Conflict — wait and retry with the same ID. Server-side idempotency is best effort, so make the sending system safe: one stable ID per event, and never retry the same event under a new ID.

Outbound. Your endpoint must respond within 10 seconds. Return 200 OK immediately and do the real work asynchronously. Deduplicate on [CALL_ID], since the same call can legitimately trigger several events. Failed deliveries are logged under Webhooks → Outgoing Webhook Requests.

TODO

Confirm and document Moja’s outbound retry policy — whether failed deliveries are retried at all, how many attempts, and with what backoff. The current help center documents the 10-second timeout and the failure log, but not retry behavior. Receivers should be built idempotent regardless.

Verify it works

Outgoing:

1. Use the Test Webhook button in the dashboard to send a sample payload to your endpoint.
2. Confirm your endpoint returns 200 OK inside 10 seconds.
3. Attach the webhook to a campaign, target, or RTB formula.
4. Place a test call and confirm the delivery appears under Webhooks → Outgoing Webhook Requests with a success status.
5. Confirm every placeholder in your template resolved to a value, and that no raw [TAG_NAME] strings arrived.

Incoming:

1. Send a request with a known-good moja_auth_key and confirm you get a 200 with "success": true.
2. Send one with a bad key and confirm you get 401 — this proves you are hitting the endpoint you think you are.
3. Confirm the effect landed on the call record in reporting, not just that the request was accepted.

Authenticating deliveries to your endpoint

Moja does not sign outgoing webhook payloads with a shared secret. Authenticate them by putting your own credential in the custom headers of the webhook template:

{
  "Authorization": "Bearer your-api-token",
  "X-Custom-Header": "custom-value"
}

Caution

Because there is no payload signature, treat webhook contents as unverified until you have checked the header credential. Do not rely on source IP alone unless you have confirmed the current egress ranges with Moja Support.

Troubleshooting

Symptom	Likely cause	Fix
No webhooks arriving	The webhook was saved but never attached to a campaign, target, or RTB formula	Attach it under Campaign → Outgoing webhooks
Still no webhooks after attaching	Endpoint unreachable, or your firewall is blocking Moja	Check delivery status under Webhooks → Outgoing Webhook Requests, then test your endpoint from outside your network
Payload contains literal [CONVERTED]	That tag is not populated for the event that fired	Move the tag to a later event such as call.completed, or handle placeholder strings in your receiver
Placeholders never substitute	Tag name is lowercase, misspelled, or missing brackets	Use uppercase inside square brackets
Deliveries time out	Your endpoint does work before responding	Return 200 OK first, process asynchronously
401 Unauthorized on an incoming webhook	moja_auth_key missing from the URL, or invalid	Copy the exact URL from Webhooks → Incoming; header auth is not supported
Duplicate processing on your side	Several events fired for one call, or a retry	Deduplicate on [CALL_ID], and send a stable transaction_id on inbound requests

Related

• Revenue postbacks
• Dynamic Number Insertion
• Outbound webhooks guide
• Inbound webhooks guide
• Understanding webhooks, agent availability, and call flow