Asterisk CURL: make HTTP dialplan lookups bounded and auditable

Treat CURL as a remote dependency in the active dialplan

CURL(url,post-data) reads remote content with HTTP GET by default and uses POST when post-data is supplied. Writing to CURL(url) retrieves with GET and writes to the named destination file. Neither form turns a network result into a routing fact by itself.

Give each lookup a named owner, fixed purpose, approved destination and explicit fallback. Keep file-writing behavior out of externally controlled paths; the Asterisk reference notes that live_dangerously=no restricts function writes from external protocols but does not restrict reads.

Construct one approved URL without leaking or reinterpreting input

Keep the scheme, host, port and path under dialplan or configuration control. Encode only the dynamic URI component with URIENCODE() instead of concatenating raw caller, header or database text into a URL. Do not place secrets or personal data in a query string or routine log.

A syntactically valid encoded component does not authorize a destination. Apply a narrow destination allowlist, outbound network policy and least-privilege service credential outside the dialplan, and keep redirects disabled unless the resulting destination policy is understood and verified.

Set options at the narrowest scope and record the effective contract

CURLOPT(key) settings may be global or per channel; channel settings override global settings, while HTTP headers are added. Prefer channel-scoped values for a call-specific lookup, and record any inherited global defaults before diagnosing an unexpected result.

The current reference exposes connection, DNS, HTTP response, redirect, proxy, authentication, TLS verification, hash-compatibility and failure-code controls. Preserve only the option names and redacted values needed for the trace; never emit cookies, user-password strings, proxy credentials, private-key passphrases or authorization headers.

Bound connection time separately from the whole transfer

Asterisk maps conntimeout to libcurl connection-timeout controls and httptimeout to whole-transfer timeout controls in the reviewed implementation. libcurl documents that the connection phase includes name resolution and protocol handshakes, and that the connection limit is included inside the overall transfer limit.

Choose explicit values from the call-path budget and the fallback requirement. A timeout is a controlled failure boundary, not proof that DNS, TCP, TLS, the remote application or its response body was the cause.

Validate transport, HTTP policy and response schema in order

Use failurecodes for the HTTP response codes the application contract treats as errors. Keep redirect following and its maximum explicit. Preserve a bounded result length and a non-sensitive correlation identifier; do not log the entire response by default.

Store a successful response in a named channel variable before parsing. JSON_DECODE(varname,item[,separator[,options]]) returns an empty string when the requested key is not found, so an empty parsed value alone does not distinguish missing key, blank value, empty response or a failed transfer. Validate the expected schema and route each invalid case to a safe fallback.

Test the remote lookup as failure-prone call-path logic

In an authorized staging context, exercise a valid response, missing key, malformed body, listed failure code, refused connection, slow connection, slow response and redirect. Capture the effective channel options, elapsed time, redacted result classification and exact fallback branch.

Repeat after a reload and on each supported installed version if global defaults or module behavior matter. Restore temporary logging and test data. A successful lookup does not prove remote-service availability, production latency, route correctness, media or compatibility; this guide is documentation-derived.

Validate a remote result before parsing or routing

The dialplan input guide separates bounded response presence, character policy, complete shape and field extraction.