In order for your application to receive messages, you need to establish a URL to which Redox can POST. We call this a Destination record.
Configuring Your Destination
A Destination is how you receive data from your integrated partners through Redox.
There are 7 steps to configuring a Destination:
- When logged into your organization on Redox, select Destinations from the side nav. Create a Destination for your Organization.
- Name your Destination. This is the name your data sharing partners will see when you have live integrations, so err on the side of being specific. After entering a name, you will be directed to your Destination’s Settings page.
- Select the appropriate “Environment Type”. If you’re just getting started, your only option will be “Development”. If you are working with us, you will be able to select “Staging” or “Production”. In order to create a Staging or Production Destination contact: firstname.lastname@example.org
- Select appropriate Data Format. This is the format in which your destination will receive data. For our digital health application partners, this will almost always be JSON.
- Establish your Endpoint. This is the URL that you expose for Redox to POST to. See below for detailed instructions on how to Setup your Destination Endpoint.
- Set a Verification Token. We will send this in the ‘verification-token’ field of the HTTP request header. It is included in every request Redox makes to your endpoint. This is how you can ensure the communication is coming from Redox.
- Click Verify and Save. This will send a special GET request to your endpoint to verify you are listening. You will receive a “Success!” response when things are setup properly.
Setting Up Your Destination Endpoint
First, you’ll need to prepare the URL that will act as your Destination Endpoint. This URL will need to be accessible by Redox’s servers and be able to receive both the POST data that is sent when an update happens and also accept GET requests in order to verify the URL with Redox. An HTTPS endpoint is required for both Staging and Production destinations.
Note: SSL certificates for HTTPS destinations cannot be self-signed. Development destinations do not need to be HTTPS.
This URL should return a 200 OK HTTP response when you receive and process messages from RedoxEngine. If there is an issue with the message or you have an issue processing it, you can return a 400 Bad Request HTTP response, which will get logged as an error. In fact, any response code 400 or above will log an error, notifying both you and the Redox team that something went wrong. Please see our article on HTTP status codes for more information about status codes and the impacts of sending a 400 response.
Handling Verification Requests
When you click Verify and Save, RedoxEngine will make a POST or a GET request to your Destination’s Redox API Endpoint in order to verify the validity of the URL.
Important Note: Using GET for verification will be deprecated on or after December 31, 2018. You can continue using this method in the interim, but Redox recommends using POSTs.
Verification with a POST from Redox will include a header and a JSON body with a challenge value.
Ex. POST request header:
Ex. POST body:
A GET verification request from Redox will also include the same header, with an additional query string appended to the URL with the challenge value.
Ex. URL with query string:
When your server receives one of these requests, it needs to:
- Verify the verification-token matches the one you supplied when creating your Destination. This is a security check so that your server knows the request is being made by RedoxEngine and relates to the Destination you just configured.
- Render a response to the POST or GET request that includes only the challenge value. This confirms that this server is configured to accept POSTs from Redox, and is used for security verification on RedoxEngine’s side.
Example of a response to the verification request:
The verification step is based on W3C’s WebSub, and we have a 15 minute video to walk you through the challenge step.
Q. How can my endpoint distinguish between a verification POST and a non-verification POST from Redox?
A. Verification POSTs will include a challenge value and your destination’s verification token (that you specified when you set up the destination record) in the body of the POST. Non-verification POSTs from Redox will always include the verification token in the header of the message.
Q. What are some helpful troubleshooting tips?
A. Troubleshooting verification with a new destination endpoint will be easier if you first remove encryption and troubleshoot it as an HTTP endpoint, which will give you more insight into the message your endpoint is receiving and your endpoint’s response. Before you remove encryption be sure to set your destination’s verification token to a test value in your dashboard (something like “123”).