Processing Requests

As described in Data Exchange via Redox, a system integrated to Redox can receive data or respond to requests from an initiating system via the Redox API. In either case, the requirements to receive a request are nearly the same, though details on error modes and response expectations differ.

The process of receiving Redox API requests is broken down into two sections:

  1. Setting up & Verifying a Destination
  2. Responding to Requests from Redox

Setting Up & Verifying a Redox API Endpoint

In order to receive data or requests via the Redox API, you must create an Endpoint configuration that defines a URL that Redox can send requests to.

Endpoint Configuration

Within the Redox Dashboard, navigate to the “Developer” page via the main navigation menu. On this page, select the “Endpoint” tab and click “Create Endpoint”.

All new users to the Redox dashboard will find a default “Redox API Endpoint” configuration that can be used for generating test requests. See Getting Started for a usage tutorial.

Endpoint Requirements

Once created, you can specify an endpoint URL for your system to receive requests from Redox.

This endpoint must:

  • Be publicly accessible from the internet
  • Utilize SSL/TLS encryption (URL begins with https://)
    [not required for endpoints created in the Development environment]
  • Accept POST requests (how Redox sends all requests)
  • Be able to verify the origination of each request (see below)

Request Verification

In order to ensure that your system only processes data legitimately received from Redox, your endpoint should verify that Redox is the origin of every incoming request. This is possible by configuring a secret verification token value for your endpoint within the Redox Dashboard.

Every request made to your system by Redox will contain this value in the following headers:

"authorization" : "Bearer <your-verification-token>"
"verification-token" : "<your-verification-token>"

Before processing the request, your system should validate that this token correctly matches the secret verification token value configured in the Redox Dashboard. A valid verification token indicates that the incoming request did in fact come from Redox.

Treat this token akin to a password. It should be a unique, long alphanumeric string value that is difficult to brute force or guess.

It may be changed at any time via the Developer page of the Dashboard.

Endpoint Verification

Whenever you save your endpoint settings, Redox will send a test verification request to the endpoint specified. This ensures that your destination endpoint is correctly validating requests in the event of any configuration changes.

This verification request can be sent as a GET or a POST request, depending on your endpoint settings.

POST (recommended)

If the “Verification Method” is set to POST, the specified endpoint will receive a request with the following payload body:

{
   "verification-token":"<your-verification-token>",
   "challenge":"2e73f864-a0e9-4764-a7d5-91fe5836db22"
}

GET

If the “Verification Method” is set to GET, the specified endpoint will receive a request with a query string containing two values:

?challenge=2e73f864-a0e9-4764-a7d5-91fe5836db22&verification-token=your-verification-token

Completing Verification

In either case, in order to verify your endpoint and successfully save and apply your endpoint settings, your system must:

  1. Verify that the verification-token value provided matches the one you supplied in the Dashboard
  2. Respond to the POST or GET request with the challenge value provided anywhere in the body of the response:
{
   "challenge":"2e73f864-a0e9-4764-a7d5-91fe5836db22" 
}
Verification Requests vs. Live Traffic

Live traffic will not contain a challenge or verification-token value in the body or query string of the request. As such, once verified, your endpoint does not need to return the challenge value when it is not provided.

Instead, as described under “Request Verification” above, your endpoint will receive live traffic payloads that include the following headers to aid in the verification process:

"authorization" : "Bearer <your-verification-token>"
"verification-token" : "<your-verification-token>"


Responding to Requests from Redox

Depending on the request received, your system or application will need to understand what Redox expects of the response returned. Specifically, response expectations differ based on whether or not the originating system is expecting a response.

The payload contents of requests sent from Redox are defined in our data model reference: https://developer.redoxengine.com/data-models/

To process requests appropriately, see the following documentation pages:

ActionData FlowLog Type
RECEIVEAsynchronous (one-way)RECEIVE
RESPONDSynchronous (two-way)RESPOND

RECEIVE or RESPOND is usually determined by the event type and workflow set up for your integration. See Data Models & Event Types for more details.