---
title: "SWML inbound call webhook"
method: POST
path: "inboundCallWebhook"
tags: ["SWML Webhook"]
---

# SWML inbound call webhook

`POST inboundCallWebhook` (webhook)

Payload sent by SignalWire to a SWML calling webhook URL when SWML is fetched for a call. This includes inbound calls arriving on a phone number configured with a SWML calling handler, and outbound REST-initiated calls that point at a SWML URL. The same payload shape is also used when the SWML calling `transfer` or `execute` method targets an external URL — in those cases, the `params` object carries the values supplied to that step.

The webhook URL is expected to respond with the SWML document to execute for the call.

## Payload

- object — Payload sent by SignalWire to a SWML calling webhook URL when SWML is fetched for a call. This includes inbound calls arriving on a phone number configured with a SWML calling handler, and outbound REST-initiated calls that point at a SWML URL. The same payload shape is also used when the SWML calling `transfer` or `execute` method targets an external URL — in those cases, the `params` object carries the values supplied to that step. The webhook URL is expected to respond with the SWML document to execute for the call.
  - `call` object, required — The call that triggered this fetch.
    - `call_id` string, required — A unique identifier for the call.
    - `node_id` string, required — A unique identifier for the node handling the call.
    - `segment_id` string, required — A unique identifier for the current call segment.
    - `tag` string — The tag you assigned to this call when it was created, if any.
    - `call_state` string, required — The current state of the call.
    - `direction` 'inbound' | 'outbound', required — The direction of the call.
    - `type` 'sip' | 'phone' | 'webrtc', required — The type of call.
    - `from` string, required — The number/URI that initiated this call.
    - `to` string, required — The number/URI of the destination of this call.
    - `from_number` string — The phone number that initiated this call. Present for phone calls (`type` is `phone`); SIP and WebRTC calls expose the originator through `from` instead.
    - `to_number` string — The destination phone number of this call. Present for phone calls (`type` is `phone`); SIP and WebRTC calls expose the destination through `to` instead.
    - `dial_winner` 'true' — Set to `"true"` when this call won a parallel dial. Omitted otherwise.
    - `headers` object[], required — The headers associated with this call.
      - `name` string, required — The name of the header.
      - `value` string, required — The value of the header.
    - `parent` object — The call that created this call. Present only when this call has a parent.
      - `device_type` 'sip' | 'phone' | 'webrtc', required — The device type of the parent call.
      - `call_id` string, required — A unique identifier for the parent call.
      - `node_id` string, required — A unique identifier for the node handling the parent call.
    - `peer` object — The call this call is bridged to. Present only when this call has a peer.
      - `call_id` string, required — A unique identifier for the peer call.
      - `node_id` string, required — A unique identifier for the node handling the peer call.
    - `sip_data` object — SIP-specific data. Present only when `type` is `sip`.
      - `sip_req_host` string, required — The host portion of the SIP request URI.
      - `sip_req_uri` string, required — The full SIP request URI.
      - `sip_req_user` string, required — The user portion of the SIP request URI.
      - `sip_from_host` string, required — The host portion of the SIP From header.
      - `sip_from_uri` string, required — The full URI from the SIP From header.
      - `sip_from_user` string, required — The user portion of the SIP From header.
      - `sip_to_host` string, required — The host portion of the SIP To header.
      - `sip_to_uri` string, required — The full URI from the SIP To header.
      - `sip_to_user` string, required — The user portion of the SIP To header.
      - `sip_contact_user` string, required — The user portion of the SIP Contact header.
      - `sip_contact_port` string, required — The port from the SIP Contact header.
      - `sip_contact_uri` string, required — The full URI from the SIP Contact header.
      - `sip_contact_host` string, required — The host portion of the SIP Contact header.
      - `sip_contact_params` object, required — Additional parameters from the SIP Contact header.
    - `project_id` string, uuid, required — The Project ID this call belongs to.
    - `space_id` string, uuid, required — The Space ID this call belongs to.
  - `vars` object, required — Script-scope variables for this call session. Empty on the initial document fetch.
  - `envs` object, required — Environment variables available to this call's SWML document, which you can reference as `${envs.<key>}`. Combines the variables you've configured at the account or project level with any `custom_variables` you passed on the outbound [Call commands](/docs/apis/rest/calls/call-commands) request. Keys are case-sensitive. When a `custom_variables` key exactly matches an account- or project-level variable, including case, the value from the request wins; if they differ only in case, both are kept as separate variables.
  - `params` object, required — Parameters passed via a SWML calling `execute` or `transfer` step. An empty object on the initial document fetch.

## Acknowledgement `200`

Webhook received

---

[API](https://skmtc.net/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.net/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/versions/05c5164b85c7/schema)