SignalWire Calling Webhooks API

Callbacks about a call: the SWML document request sent when a call arrives, and the progress of work you started on it such as a transcription or a background audio stream.

GitHub OpenAPI

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/signalwire:signalwire-calling-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

signalwire-calling-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: SignalWire REST Calling Webhooks API
  version: 1.0.0
  contact:
    name: SignalWire
    url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011
    email: support@signalwire.com
  license:
    name: MIT
    url: https://github.com/signalwire/docs/blob/main/LICENSE
  termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement
  description: 'Callbacks about a call: the SWML document request sent when a call arrives, and the progress of work you started on it such as a transcription or a background audio stream.'
servers:
- url: https://{space_name}.signalwire.com
  description: SignalWire API
  variables:
    space_name:
      default: '{Your_Space_Name}'
      description: Your SignalWire Space name
security:
- SignalWireBasicAuth: []
tags:
- name: Calling Webhooks
  description: 'Callbacks about a call: the SWML document request sent when a call arrives, and the progress of work you started on it such as a transcription or a background audio stream.'
  externalDocs:
    url: https://signalwire.com/docs/apis
    description: Developer documentation on calling webhooks
paths: {}
webhooks:
  inboundCallWebhook:
    post:
      operationId: inbound_call_webhook
      summary: SWML inbound call webhook
      description: '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.'
      parameters: []
      responses:
        '200':
          description: Webhook received
      tags:
      - Calling Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhooks.Calling.InboundCallWebhookPayload'
      security:
      - {}
  streamStatusCallback:
    post:
      operationId: stream_status_callback
      summary: Stream status callback
      description: 'Sent to your `status_url` when a background audio stream started with

        `calling.stream` changes state. `params.state` is `streaming` when the stream

        starts and `finished` when it ends.


        Status callbacks are advisory, best-effort notifications — delivery can be delayed or fail silently, so don''t gate time-critical actions on receiving one. See Status callback reliability.'
      parameters: []
      responses:
        '200':
          description: Webhook received
      tags:
      - Calling Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhooks.Calling.StreamStatusCallbackPayload'
      security:
      - {}
  transcribeStatusCallback:
    post:
      operationId: transcribe_status_callback
      summary: Transcript status callback
      description: 'Sent to your `status_url` when the call''s transcription is ready.

        `calling.transcript.completed` includes the transcribed text;

        `calling.transcript.failed` means the call could not be transcribed.


        Status callbacks are advisory, best-effort notifications — delivery can be delayed or fail silently, so don''t gate time-critical actions on receiving one. See Status callback reliability.'
      parameters: []
      responses:
        '200':
          description: Webhook received
      tags:
      - Calling Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhooks.Calling.TranscribeStatusCallbackPayload'
      security:
      - {}
components:
  schemas:
    Webhooks.Calling.InboundCallWebhookPayload:
      type: object
      required:
      - call
      - vars
      - envs
      - params
      properties:
        call:
          allOf:
          - $ref: '#/components/schemas/Webhooks.Calling.InboundCallContext'
          description: The call that triggered this fetch.
        vars:
          type: object
          unevaluatedProperties: {}
          description: Script-scope variables for this call session. Empty on the initial document fetch.
          examples:
          - user_selection: '1'
        envs:
          type: object
          unevaluatedProperties: {}
          description: '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.'
          examples:
          - api_key: <YOUR_API_KEY>
            webhook_url: https://example.com/webhook
            id: '12345'
            case_number: '54321'
        params:
          type: object
          unevaluatedProperties: {}
          description: Parameters passed via a SWML calling `execute` or `transfer` step. An empty object on the initial document fetch.
          examples:
          - department: sales
      unevaluatedProperties:
        not: {}
    Webhooks.Calling.TranscribeStatusCallbackPayload:
      type: object
      required:
      - event_type
      - timestamp
      - project_id
      - space_id
      - params
      properties:
        event_type:
          type: string
          enum:
          - calling.transcript.completed
          - calling.transcript.failed
          description: Whether the transcription completed or failed.
          examples:
          - calling.transcript.completed
        timestamp:
          type: number
          description: When the event was sent, as a Unix timestamp in seconds.
          examples:
          - 1777565701.5623918
        project_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: Your project ID.
          examples:
          - 4d0d6f16-5881-4fcc-92a4-02c51a91954d
        space_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: Your Space ID.
          examples:
          - 451ed9ff-e568-4222-8af9-4f9ab7428d09
        params:
          type: object
          properties:
            id:
              allOf:
              - $ref: '#/components/schemas/uuid'
              description: Unique ID for this transcript.
              examples:
              - 0ec5a4da-46b9-4d2c-b724-151add8d4d08
            call_id:
              allOf:
              - $ref: '#/components/schemas/uuid'
              description: ID of the call that was transcribed.
              examples:
              - 2e1e66e5-5d07-413d-9668-55542992eec0
            segment_id:
              allOf:
              - $ref: '#/components/schemas/uuid'
              description: ID of the call leg that was transcribed.
              examples:
              - 2e1e66e5-5d07-413d-9668-55542992eec0
            text:
              type: string
              description: The transcribed text of the call. Omitted when there is no transcribed text.
              examples:
              - A long time ago in a galaxy far, far away, Luke, I am your father. Do or do not, there is no try. May the force be with you. These aren't the droids you're looking for. I find your lack of faith disturbing. The force will be with you always.
          required:
          - id
          - call_id
          - segment_id
          unevaluatedProperties:
            not: {}
          description: The transcript.
      unevaluatedProperties:
        not: {}
    Webhooks.Calling.InboundCallParent:
      type: object
      required:
      - device_type
      - call_id
      - node_id
      properties:
        device_type:
          type: string
          enum:
          - sip
          - phone
          - webrtc
          description: The device type of the parent call.
          examples:
          - phone
        call_id:
          type: string
          description: A unique identifier for the parent call.
          examples:
          - a1b2c3d4-1111-2222-3333-444455556666
        node_id:
          type: string
          description: A unique identifier for the node handling the parent call.
          examples:
          - a1b2c3d4-1111-2222-3333-444455556666
      unevaluatedProperties:
        not: {}
      description: The call that created this call. Present only when this call has a parent — for example, a leg created by a `connect` or transfer.
      title: Parent call
    Webhooks.Calling.InboundCallHeader:
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: The name of the header.
          examples:
          - X-Custom-Header
        value:
          type: string
          description: The value of the header.
          examples:
          - custom-value
      unevaluatedProperties:
        not: {}
      description: A single header associated with the call.
      title: Call header
    Webhooks.Calling.StreamStatusCallbackPayload:
      type: object
      required:
      - event_type
      - event_channel
      - timestamp
      - project_id
      - space_id
      - params
      properties:
        event_type:
          type: string
          enum:
          - calling.call.stream
          description: The type of event. Always `calling.call.stream` for stream status callbacks.
          examples:
          - calling.call.stream
        event_channel:
          type: string
          description: The channel the event was delivered on.
          examples:
          - swml:451ed9ff-e568-4222-8af9-4f9ab7428d09
        timestamp:
          type: number
          description: When the event was sent, as a Unix timestamp in seconds.
          examples:
          - 1777565701.5623918
        project_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: Your project ID.
          examples:
          - 4d0d6f16-5881-4fcc-92a4-02c51a91954d
        space_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: Your Space ID.
          examples:
          - 451ed9ff-e568-4222-8af9-4f9ab7428d09
        params:
          type: object
          properties:
            call_id:
              allOf:
              - $ref: '#/components/schemas/uuid'
              description: ID of the call being streamed.
              examples:
              - 2e1e66e5-5d07-413d-9668-55542992eec0
            node_id:
              allOf:
              - $ref: '#/components/schemas/uuid'
              description: ID of the node the call is on.
              examples:
              - a0d4e6e5-5d07-413d-9668-55542992eec0
            segment_id:
              allOf:
              - $ref: '#/components/schemas/uuid'
              description: ID of the call segment being streamed.
              examples:
              - 2e1e66e5-5d07-413d-9668-55542992eec0
            tag:
              type: string
              description: The tag associated with the call. Present only when a tag was set on the call.
              examples:
              - my-tag
            control_id:
              type: string
              description: The control ID used to control the stream, as set in `calling.stream`.
              examples:
              - stream-control-1
            state:
              type: string
              enum:
              - streaming
              - finished
              description: The stream state. `streaming` when the stream starts, `finished` when it ends.
              examples:
              - streaming
            url:
              type: string
              description: The WebSocket URL the audio is being streamed to.
              examples:
              - wss://example.com/stream
            name:
              type: string
              description: The friendly name of the stream. Present when a `name` was set on the stream.
              examples:
              - customer-support-recording
          required:
          - call_id
          - node_id
          - segment_id
          - control_id
          - state
          - url
          unevaluatedProperties:
            not: {}
          description: Details about the stream.
      unevaluatedProperties:
        not: {}
    Webhooks.Calling.InboundCallPeer:
      type: object
      required:
      - call_id
      - node_id
      properties:
        call_id:
          type: string
          description: A unique identifier for the peer call.
          examples:
          - a1b2c3d4-1111-2222-3333-444455556666
        node_id:
          type: string
          description: A unique identifier for the node handling the peer call.
          examples:
          - a1b2c3d4-1111-2222-3333-444455556666
      unevaluatedProperties:
        not: {}
      description: The call this call is bridged to. Present only when this call has a peer.
      title: Peer call
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
    Webhooks.Calling.InboundCallContext:
      type: object
      required:
      - call_id
      - node_id
      - segment_id
      - call_state
      - direction
      - type
      - from
      - to
      - headers
      - project_id
      - space_id
      properties:
        call_id:
          type: string
          description: A unique identifier for the call.
          examples:
          - c2d3e4f5-a6b7-8901-cdef-234567890abc
        node_id:
          type: string
          description: A unique identifier for the node handling the call.
          examples:
          - a1b2c3d4-1111-2222-3333-444455556666
        segment_id:
          type: string
          description: A unique identifier for the current call segment.
          examples:
          - d3e4f5a6-b7c8-9012-defa-345678901bcd
        tag:
          type: string
          description: The tag you assigned to this call when it was created, if any.
          examples:
          - support-queue
        call_state:
          type: string
          description: The current state of the call.
          examples:
          - created
        direction:
          type: string
          enum:
          - inbound
          - outbound
          description: The direction of the call.
          examples:
          - inbound
        type:
          type: string
          enum:
          - sip
          - phone
          - webrtc
          description: The type of call.
          examples:
          - sip
        from:
          type: string
          description: The number/URI that initiated this call.
          examples:
          - sip:user@example.com
        to:
          type: string
          description: The number/URI of the destination of this call.
          examples:
          - sip:destination@yourdomain.com
        from_number:
          type: string
          description: The phone number that initiated this call. Present for phone calls (`type` is `phone`); SIP and WebRTC calls expose the originator through `from` instead.
          examples:
          - '+12223334444'
        to_number:
          type: string
          description: The destination phone number of this call. Present for phone calls (`type` is `phone`); SIP and WebRTC calls expose the destination through `to` instead.
          examples:
          - '+12223334445'
        dial_winner:
          type: string
          enum:
          - 'true'
          description: Set to `"true"` when this call won a parallel dial. Omitted otherwise.
          examples:
          - 'true'
        headers:
          type: array
          items:
            $ref: '#/components/schemas/Webhooks.Calling.InboundCallHeader'
          description: The headers associated with this call.
          examples:
          - []
        parent:
          allOf:
          - $ref: '#/components/schemas/Webhooks.Calling.InboundCallParent'
          description: The call that created this call. Present only when this call has a parent.
        peer:
          allOf:
          - $ref: '#/components/schemas/Webhooks.Calling.InboundCallPeer'
          description: The call this call is bridged to. Present only when this call has a peer.
        sip_data:
          allOf:
          - $ref: '#/components/schemas/Webhooks.Calling.InboundCallSipData'
          description: SIP-specific data. Present only when `type` is `sip`.
        project_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The Project ID this call belongs to.
          examples:
          - b2c3d4e5-f6a7-8901-bcde-f12345678901
        space_id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The Space ID this call belongs to.
          examples:
          - d3e4f5a6-b7c8-9012-defa-345678901bcd
      unevaluatedProperties:
        not: {}
      description: Information about the call that triggered the SWML document fetch.
      title: Inbound call
    Webhooks.Calling.InboundCallSipData:
      type: object
      required:
      - sip_req_host
      - sip_req_uri
      - sip_req_user
      - sip_from_host
      - sip_from_uri
      - sip_from_user
      - sip_to_host
      - sip_to_uri
      - sip_to_user
      - sip_contact_user
      - sip_contact_port
      - sip_contact_uri
      - sip_contact_host
      - sip_contact_params
      properties:
        sip_req_host:
          type: string
          description: The host portion of the SIP request URI.
          examples:
          - yourdomain.com
        sip_req_uri:
          type: string
          description: The full SIP request URI.
          examples:
          - destination@yourdomain.com
        sip_req_user:
          type: string
          description: The user portion of the SIP request URI.
          examples:
          - destination
        sip_from_host:
          type: string
          description: The host portion of the SIP From header.
          examples:
          - example.com
        sip_from_uri:
          type: string
          description: The full URI from the SIP From header.
          examples:
          - user@example.com
        sip_from_user:
          type: string
          description: The user portion of the SIP From header.
          examples:
          - user
        sip_to_host:
          type: string
          description: The host portion of the SIP To header.
          examples:
          - yourdomain.com
        sip_to_uri:
          type: string
          description: The full URI from the SIP To header.
          examples:
          - destination@yourdomain.com
        sip_to_user:
          type: string
          description: The user portion of the SIP To header.
          examples:
          - destination
        sip_contact_user:
          type: string
          description: The user portion of the SIP Contact header.
          examples:
          - user
        sip_contact_port:
          type: string
          description: The port from the SIP Contact header.
          examples:
          - '5060'
        sip_contact_uri:
          type: string
          description: The full URI from the SIP Contact header.
          examples:
          - user@192.168.1.100:5060
        sip_contact_host:
          type: string
          description: The host portion of the SIP Contact header.
          examples:
          - 192.168.1.100
        sip_contact_params:
          type: object
          unevaluatedProperties: {}
          description: Additional parameters from the SIP Contact header.
          examples:
          - {}
      unevaluatedProperties:
        not: {}
      description: SIP-specific data for SIP calls. Only present when `call.type` is `sip`.
      title: Inbound call SIP data
  securitySchemes:
    SignalWireBasicAuth:
      type: http
      scheme: Basic
      description: 'SignalWire Basic Authentication using Project ID and API Token.


        The client sends HTTP requests with the Authorization header containing

        the word Basic followed by a space and a base64-encoded string of project_id:token.

        The project ID will be used as the username and the API token as the password.


        Example:

        ```

        Authorization: Basic base64(project_id:token)

        ```'
      x-fern-basic:
        username:
          name: project_id
          env: SIGNALWIRE_PROJECT_ID
        password:
          name: api_token
          env: SIGNALWIRE_API_TOKEN
    SignalWireBearerAuth:
      type: http
      scheme: Bearer
      description: 'SignalWire Bearer Token Authentication for subscriber endpoints.

        The client sends HTTP requests with the Authorization header containing

        the word Bearer followed by a space and the subscriber token.


        Example:

        ```

        Authorization: Bearer <subscriber_token>

        ```'