Processing Requests (Destination)

As described in Sources, Destinations, & Subscriptions, a system configured as a destination can receive data or respond to requests from a source 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 Destination

In order to receive data or requests via the Redox API, you must create and configure a destination record that defines an endpoint that Redox can send requests to.

Destination Configuration

Within the Redox Dashboard, navigate to an existing destination record (or create a new one) with communication method “Redox API” and data format “JSON”.

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

Endpoint

The settings tab of a destination record contains a field where you can specify an endpoint on 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 “development” destinations]
  • 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 destination within the Redox Dashboard.

Every request made to your system by Redox will contain this value in the verification-token header:

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

Before processing the request, your system should validate that this token correctly matches the value configured for your destination. 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 destination settings in the Dashboard.

Endpoint Verification

Whenever you save your destination 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 destination settings.

POST (recommended)

If the “Verification Method” is set to POST, the specified destination 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 destination 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 destination endpoint and successfully save and apply your destination 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 in the body of the response:
{
   "challenge":"2e73f864-a0e9-4764-a7d5-91fe5836db22" 
}

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 source system is expecting a response from your destination.

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.