SignalWire Calling Webhooks API

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](/docs/platform/webhooks#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](/docs/platform/webhooks#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.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.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.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.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
    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.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.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.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
  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>

        ```'