[API Change] SWML/cXML Webhooks expose script_type instead of used_for

[RafaelPChequer]

references: signalwire/cloud-product#18953

Summary

SWML and cXML Webhooks currently expose the handler-use property as used_for. The equivalent property on SWML and cXML Scripts is already called script_type. They are the same concept with the same values, so the two names were an inconsistency between closely related resources.

Webhooks will expose script_type instead:

• Responses return script_type and no longer return used_for.
• Requests accept script_type. used_for is still accepted as a deprecated alias so existing integrations keep working. If both are sent, script_type wins regardless of key order.
• Validation errors are reported against script_type, including when the value was supplied as used_for.

The dashboard forms for these resources are relabelled from "Used For" to "Script Type". No values change: the accepted set is unchanged.

Go-live: not yet scheduled. The implementing change is still in review, and one open decision may affect the response shape — see Open question below. Please hold publication until that is settled and a deploy date is known.

Authentication and scope

Unchanged by this change. These endpoints use the standard Fabric REST authentication and are scoped to the project of the authenticated credentials; a request for a resource outside that project returns 404.

Base URL: https://<your-space>.signalwire.com

Endpoints

The change affects the request and response bodies of the existing SWML and cXML Webhook endpoints. No paths are added or removed.

Method	Path	Description
GET	/api/fabric/resources/swml_webhooks	List SWML Webhooks
POST	/api/fabric/resources/swml_webhooks	Create a SWML Webhook
GET	/api/fabric/resources/swml_webhooks/{id}	Retrieve a SWML Webhook
PUT / PATCH	/api/fabric/resources/swml_webhooks/{id}	Update a SWML Webhook
DELETE	/api/fabric/resources/swml_webhooks/{id}	Delete a SWML Webhook
GET	/api/fabric/resources/cxml_webhooks	List cXML Webhooks
POST	/api/fabric/resources/cxml_webhooks	Create a cXML Webhook
GET	/api/fabric/resources/cxml_webhooks/{id}	Retrieve a cXML Webhook
PUT / PATCH	/api/fabric/resources/cxml_webhooks/{id}	Update a cXML Webhook
DELETE	/api/fabric/resources/cxml_webhooks/{id}	Delete a cXML Webhook

Limitations

• script_type accepts calling or messaging for SWML Webhooks. A value outside that set is rejected.
• cXML Webhooks additionally accept faxing.
• Omitting script_type on create leaves the resource at the default, calling.
• Sending script_type as an empty string is rejected rather than treated as omitted.
• used_for is accepted on input as a deprecated alias only. It is not returned in responses, so a client that writes used_for and then reads the response back must read script_type.

Fields

Returned object:

Field	Type	Notes
id	string (uuid)
name	string	Display name, max 50 characters
script_type	string	calling or messaging (cXML also faxing). Replaces used_for, which is no longer returned.
primary_request_url	string
primary_request_method	string	GET or POST
fallback_request_url	string
fallback_request_method	string	GET or POST
status_callback_url	string
status_callback_method	string	GET or POST

Writable on create and update:

Field	Required on create	Notes
name	no	Max 50 characters
script_type	no	Defaults to calling. New name; used_for still accepted as a deprecated alias
primary_request_url	yes
primary_request_method	no	Defaults to POST
fallback_request_url	no
fallback_request_method	no	Defaults to POST
status_callback_url	no
status_callback_method	no	Defaults to POST

Request and response examples

Create a SWML Webhook:

POST /api/fabric/resources/swml_webhooks
Content-Type: application/json

{
  "name": "Support line handler",
  "script_type": "messaging",
  "primary_request_url": "https://example.com/swml",
  "primary_request_method": "POST"
}

201 Created

{
  "id": "5f8a1c2e-1d3b-4a7e-9c10-2b6d4e8f0a11",
  "name": "Support line handler",
  "script_type": "messaging",
  "primary_request_url": "https://example.com/swml",
  "primary_request_method": "POST",
  "fallback_request_url": null,
  "fallback_request_method": "POST",
  "status_callback_url": null,
  "status_callback_method": "POST"
}

Update using the deprecated alias — accepted, but the response uses the new name:

PATCH /api/fabric/resources/cxml_webhooks/5f8a1c2e-1d3b-4a7e-9c10-2b6d4e8f0a11
Content-Type: application/json

{ "used_for": "calling" }

200 OK

{
  "id": "5f8a1c2e-1d3b-4a7e-9c10-2b6d4e8f0a11",
  "name": "Support line handler",
  "script_type": "calling",
  "primary_request_url": "https://example.com/cxml",
  "primary_request_method": "POST",
  "fallback_request_url": null,
  "fallback_request_method": "POST",
  "status_callback_url": null,
  "status_callback_method": "POST"
}

Error responses

No new error codes. An invalid value is reported against script_type using the existing structured error body:

422 Unprocessable Entity

{
  "errors": [
    {
      "type": "validation_error",
      "code": "invalid_parameter",
      "message": "script_type is not included in the list",
      "attribute": "script_type",
      "url": "https://developer.signalwire.com/rest/signalwire-rest/overview/error-codes"
    }
  ]
}

Note for the docs reference: the attribute name in validation errors for this property changes from used_for to script_type, including when the client supplied used_for.

Status	When
401	Missing or invalid credentials
404	Resource not in the authenticated project
422	Validation failure, including a script_type value outside the accepted set

OpenAPI

The change is a property rename on the existing SWML and cXML Webhook schemas. For the response schema, used_for is removed and replaced by:

script_type:
  type: string
  description: >-
    The type of communications this handler is used for. Replaces the former
    `used_for` property.
  enum:
    - calling
    - messaging
  default: calling

For cXML Webhooks the enum additionally includes faxing.

For the request schemas, script_type is added as above and used_for is kept as a deprecated alias:

used_for:
  type: string
  deprecated: true
  description: >-
    Deprecated alias for `script_type`. Still accepted on input; not returned in
    responses. If both are supplied, `script_type` takes precedence.
  enum:
    - calling
    - messaging

Open question that may change the above

The implementing change currently drops used_for from responses immediately, while keeping it accepted on input. Whether to instead return both script_type and used_for for a deprecation window is still being decided. If that option is chosen, the response schema keeps used_for marked deprecated: true and the "no longer returned" wording above needs adjusting. Worth confirming before this is written up.