webhook | SignalWire

Add an API call. Multiple webhooks can be chained — they execute in order, and if earlier webhooks fail, later ones act as fallbacks.

Parameters

method

stringRequired

HTTP method for the request.

"GET" — retrieve a resource
"POST" — create a resource or submit data
"PUT" — replace a resource
"DELETE" — remove a resource
"PATCH" — partially update a resource

url

stringRequired

API endpoint URL. Supports ${variable} substitutions (use ${enc:args.param} for URL-encoded values).

opts

object

Optional configuration.

opts.headers

Record<string, string>

HTTP headers to include in the request.

opts.formParam

string

Send the JSON body as a single form parameter with this name.

opts.inputArgsAsParams

boolean

Merge function arguments into the request parameters automatically.

opts.requireArgs

string[]

Only execute this webhook if all listed arguments are present.

Returns

DataMap — Self for method chaining.

Example

import { DataMap, FunctionResult } from '@signalwire/sdk';
const weather = new DataMap('get_weather');
weather
  .purpose('Get current weather for a city')
  .parameter('city', 'string', 'City name', { required: true })
  .webhook('GET', 'https://api.weatherapi.com/v1/current.json?key=YOUR_API_KEY&q=${enc:args.city}', {
    headers: { Accept: 'application/json' },
  })
  .output(new FunctionResult('Weather: ${response.current.condition.text}'));
console.log(weather.toSwaigFunction());

Chained webhooks act as fallbacks — if the first webhook fails, the second is tried:

import { DataMap, FunctionResult } from '@signalwire/sdk';
const search = new DataMap('search');
search
  .purpose('Search across multiple providers')
  .parameter('query', 'string', 'Search query', { required: true })
  .webhook('GET', 'https://primary-api.example.com/search?q=${enc:args.query}')
  .output(new FunctionResult('Primary: ${response.result}'))
  .webhook('GET', 'https://backup-api.example.com/search?q=${enc:args.query}')
  .output(new FunctionResult('Backup: ${response.result}'))
  .fallbackOutput(new FunctionResult('All search providers are unavailable.'));