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
delay number

Delay in request execution (in seconds)

If delayMax is also defined and has a greater value, delay is used as the lower limit for calculating the request execution delay. In this case delay is an inclusive random value between delay and delayMax. The value is calculated separately for each request as milliseconds.

 
30.5

Default: 0

Minimum (if defined): 1

Maximum: 3600
delayMax number

Maximum delay in request execution (in seconds)

This value only matters if delay is also defined and has a smaller value. In this case, delayMax is used as the upper limit for calculating the request execution delay, which is an inclusive random value between delay and delayMax. The value is calculated separately for each request as milliseconds.

 
55.5

Default: 0

Minimum: greater than delay

Maximum: 3600

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"
  }
}