From 3743b6748983397c24cd5f2e32dd627d5053f458 Mon Sep 17 00:00:00 2001 From: Marco Pereira <33976946+magp18@users.noreply.github.com> Date: Mon, 17 Aug 2026 14:32:00 +0200 Subject: [PATCH 1/2] Docs :memo: Enhance outbound connection settings with headers and proxy Added support for extra HTTP headers and proxy in outbound requests. --- .../reference/app-settings/outbound.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/content/en/building/reference/app-settings/outbound.md b/content/en/building/reference/app-settings/outbound.md index ed263bf50a..2aa1ae1a30 100644 --- a/content/en/building/reference/app-settings/outbound.md +++ b/content/en/building/reference/app-settings/outbound.md @@ -62,6 +62,8 @@ Example: you want to send a referral to a facility's EMR system when a CHW refer A complex property that defines the details of the connection to the external service. It currently supports several authentication types: basic authentication, HTTP authorization request header, and a custom authentication mode for Muso SIH. +It can also include extra HTTP `headers` and an optional `proxy`. + Basic auth example: ```json @@ -84,6 +86,8 @@ If you don't provide an authentication parameter then the request will be sent w As of 3.9, the `header` type is also supported, which sends authentication credentials via a HTTP request header: `Authorization: ''`. The value is set in CHT credentials configuration, and referred to by the `value_key`, similarly to the `password_key`. The value must match the credentials needed for the third party tool, and is generally formatted as ` `. For instance, to send data to RapidPro, the value in the configuration would be set to the complete RapidPro API Token: eg `Token 123456789abcdef`. +`auth.type: "header"` only supports `name: "Authorization"`. For other headers (for example `x-api-key`), use `destination.headers`. + Header auth example: ```json { @@ -99,6 +103,47 @@ Header auth example: } ``` +#### headers +An optional object of extra HTTP headers to send with the request. Each key is the header name. Each value must be an object with exactly one of: +- `value`: a plain string sent as-is +- `value_key`: a key used to find the value in CHT credentials (same as `password_key`) + +#### proxy +An optional proxy for the outbound request. A string URL is typical, for example `http://proxy.example.com:3128`. + +Example with extra headers and a proxy (no `auth`): +```json +{ + "destination": { + "base_url": "https://example.com", + "path": "/api/v1/referral", + "proxy": "http://proxy.example.com:3128", + "headers": { + "Content-Type": { "value": "application/json" }, + "X-Source": { "value": "CHT" }, + "x-api-key": { "value_key": "example.com-api-key" } + } + } +} +``` +Example with `Authorization` auth plus an extra header: +```json +{ + "destination": { + "base_url": "https://example.com", + "path": "/api/v1/referral", + "auth": { + "type": "header", + "name": "Authorization", + "value_key": "example.com" + }, + "headers": { + "X-Source": { "value": "CHT" } + } + } +} +``` + ### mapping A complex property that declares how the payload to be sent to the `destination` should be created. From 575325a06769d30f600de2c65226547406a3c2ea Mon Sep 17 00:00:00 2001 From: Joshua Kuestersteffen Date: Thu, 3 Sep 2026 17:52:09 -0500 Subject: [PATCH 2/2] Include "added in" version plus some minor tweaks --- .../reference/app-settings/outbound.md | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/content/en/building/reference/app-settings/outbound.md b/content/en/building/reference/app-settings/outbound.md index 2aa1ae1a30..d3edd615dc 100644 --- a/content/en/building/reference/app-settings/outbound.md +++ b/content/en/building/reference/app-settings/outbound.md @@ -86,7 +86,9 @@ If you don't provide an authentication parameter then the request will be sent w As of 3.9, the `header` type is also supported, which sends authentication credentials via a HTTP request header: `Authorization: ''`. The value is set in CHT credentials configuration, and referred to by the `value_key`, similarly to the `password_key`. The value must match the credentials needed for the third party tool, and is generally formatted as ` `. For instance, to send data to RapidPro, the value in the configuration would be set to the complete RapidPro API Token: eg `Token 123456789abcdef`. +{{< callout type="info" >}} `auth.type: "header"` only supports `name: "Authorization"`. For other headers (for example `x-api-key`), use `destination.headers`. +{{< /callout >}} Header auth example: ```json @@ -104,20 +106,20 @@ Header auth example: ``` #### headers + +_Added in 5.4.0_ + An optional object of extra HTTP headers to send with the request. Each key is the header name. Each value must be an object with exactly one of: - `value`: a plain string sent as-is -- `value_key`: a key used to find the value in CHT credentials (same as `password_key`) +- `value_key`: a key used to find the value in [CHT credentials](/building/reference/api/#/Config/v1CredentialsKeyPut) -#### proxy -An optional proxy for the outbound request. A string URL is typical, for example `http://proxy.example.com:3128`. +Example with custom auth header (and no `auth` config): -Example with extra headers and a proxy (no `auth`): ```json { "destination": { "base_url": "https://example.com", "path": "/api/v1/referral", - "proxy": "http://proxy.example.com:3128", "headers": { "Content-Type": { "value": "application/json" }, "X-Source": { "value": "CHT" }, @@ -126,19 +128,25 @@ Example with extra headers and a proxy (no `auth`): } } ``` -Example with `Authorization` auth plus an extra header: + +#### proxy + +_Added in 5.4.0_ + +An optional proxy for the outbound request. A string URL is typical, for example `http://proxy.example.com:3128`. However, any valid [constructor parameters](https://undici.nodejs.org/api/ProxyAgent) for `ProxyAgent` are accepted. + +Example with `proxy`: + ```json { "destination": { "base_url": "https://example.com", - "path": "/api/v1/referral", + "path": "/api/v1/referral", + "proxy": "http://proxy.example.com:3128", "auth": { "type": "header", "name": "Authorization", "value_key": "example.com" - }, - "headers": { - "X-Source": { "value": "CHT" } } } }