webhook | SignalWire

Add an API call. Multiple webhooks can be chained. The platform tries them in order, skipping any whose requireArgs are all absent, and the first webhook it requests decides the result: if that request fails, the fallback output is used and no later webhook is tried.

Parameters

method

stringRequired

HTTP method for the request: "GET" or "POST". It is uppercased.

The platform sends GET and POST requests only. A webhook is sent as a POST when method is "POST" or when it has params, and as a GET otherwise, so "PUT", "PATCH", and "DELETE" are sent as GET.

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[]

Skip this webhook, without a request, unless at least one of the listed arguments is 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: ${current.condition.text}'));
console.log(weather.toSwaigFunction());

Chain webhooks with requireArgs to pick an endpoint by the arguments the caller gave. A failed request isn’t retried on the next webhook; it gives the fallback output:

import { DataMap, FunctionResult } from '@signalwire/sdk';
const lookup = new DataMap('find_order');
lookup
  .purpose('Find an order by order number or by email')
  .parameter('order_id', 'string', 'Order number')
  .parameter('email', 'string', 'Email address on the order')
  .webhook('GET', 'https://api.example.com/orders/${enc:args.order_id}', { requireArgs: ['order_id'] })
  .output(new FunctionResult('Order ${id} is ${status}.'))
  .webhook('GET', 'https://api.example.com/orders?email=${enc:args.email}', { requireArgs: ['email'] })
  .output(new FunctionResult('The latest order for that email is ${status}.'))
  .fallbackOutput(new FunctionResult('I could not look up that order.'));