Configuring a JSON request

In the table, you'll find the basic building blocks available for configuring your request.

Table 1. JSON request configuration
Name	JSON data type	Description	Example values
authentication	object	The type of authentication used with requests	`{ "type": "oauth", "client_id": "ddffrrvdfdewretertrgv", "access_token_url": "https://external-oauth-service/oauth2/token", "scope": [ "test" ] }` Read more about Configuring OAuth authentication. `{"type": "basic"}`
method (required)	string	The HTTP method used for requests	`GET, POST, PUT, PATCH, DELETE`
headers	object	Set of key-value pairs for defining request header names and their values You can use the available authentication data as well as contact and event data in dynamic runtime placeholders.	`{"Accept": "application/json"}` `{"x-api-key": "{authentications.api-key}"}` `{"x-contact-event": "{contact.direction}-{contact.channel_type}-{event}"}`
params	object	Set of key-value pairs for defining request query parameter names and their values You can use the available contact and event data as dynamic runtime data placeholders.	`{"event": "{event}"}` `{"filter": "source='{contact.source}'"}`
body	object	Set of key-value pairs for defining the request JSON body Supports nesting, which means values can also be specified as other JSON objects of varying depth Note: This object only applies to request methods POST, PUT, and PATCH. You can use the available contact and event data as dynamic runtime data placeholders.	`{"contact": "{contact}"}` `{"message": "Your message {contact.id} to {contact.destination} has been received."}`
condition	string	Scriptable condition for controlling whether a request should be triggered The value of the condition is evaluated at runtime. For more information, see Using conditions.	`contact.get_priority() <= 50`
timeout	number or string	Connection and read timeout in seconds	`14.5` Default: 10
proxy	string	The HTTP proxy server used with the requests	Auto-detect (default): `auto` Explicit: `<proxy-address>` Bypass: `no`
block	boolean	Whether requests should be handled in a blocking manner regardless of the associated response handling instructions This means by having the calling code wait for response data to be received before continuing with its execution flow.	`true, false` Default: false
verify	boolean	Whether SSL certificates for HTTPS requests will be verified By default, SSL verification is enabled.	`true, false` Default: true

Configuring OAuth authentication

OAuth 2.0 Client Credentials Grant authentication is supported.

In addition to configuring the authentication object inside the JSON request, define the client secret in the Authentication block. The client secret is required.

Table 2. OAuth authentication object configuration
Name	JSON Data Type	Description	Example Values
type (required)	string	Type of authentication `oauth` in this case	`oauth`
access_token_url (required)	string	Endpoint for the authorization server This is used to get the access token.	`https://oauth-service/oauth/token`
client_id (required)	string	The client identifier	`nkjihuigyuftyxtycgc`
scope	string array	Scope(s) of the access token request	`["test"]`
http_method	string	HTTP method of the access token request	`GET, POST (default)`
client_authentication_method	string	Whether client credentials are sent as a basic authentication header or in the body in the access token request	`auth_header (default), body`
include_client_id	boolean	Adds client_id to body. Applies only when client_authentication_method is header. In case client_authentication_method is body, client_id and client_secret are always in body.	`true`
extra_params	object	Extra parameters for access token request. In case http_method is POST, parameters are sent in body. For GET requests parameters are sent as query parameters.	`{ "token_format": "jwt" }`
headers	object	Overrides the default headers for the access token request	`{ "x-app-id": "id1234" }`
token_placement	string	Defines how the token is sent in the endpoint request. By default, the token is sent in the authorization header.	`auth_header (default), query`

proxy, verify and timeout properties from request configuration are used also for access token request.

OAuth examples

Example 1: Send a POST request with client credentials in a basic authentication header to request the token. The token is added to the authentication header for the endpoint request.

{
  "authentication": {
    "type": "oauth",
    "client_authentication_method": "body",
    "client_id": "ddffrrvdfdewretertrgv",
    "access_token_url": "https://external-oauth-service/oauth2/token"
  }
}

Example 2: Send a POST request with client credentials as parameters in the body of the access token request. The token is added to the authentication header for the endpoint request.

{
  "authentication": {
    "type": "oauth",
    "client_authentication_method": "body",
    "client_id": "ddffrrvdfdewretertrgv",
    "access_token_url": "https://external-oauth-service/oauth2/token"
  }
}

Example 3: Send access token request as GET. Client credentials are sent as a basic authentication header. The token is added to authentication header for the endpoint request.

{
  "authentication": {
    "type": "oauth",
    "client_authentication_method": "auth_header",
    "http_method": "POST",
    "client_id": "ddffrrvdfdewretertrgv",
    "access_token_url": "https://external-oauth-service/oauth2/token",
    "scope":  ["test", "test2"],
    "include_client_id": true,
    "token_placement": "auth_header"
  }
}

Example 4: Send access token request as GET. Client credentials are sent as a basic authentication header, but client_id is included to body parameters also. Access token is requested with specific sopes. The token is added to access query parameter for the endpoint request.

{
  "authentication": {
    "type": "oauth",
    "client_authentication_method": "auth_header",
    "http_method": "GET",
    "client_id": "ddffrrvdfdewretertrgv",
    "access_token_url": "https://external-oauth-service/oauth2/token",
    "token_placement": "query"
  }
}