Responding to asynchronous events

Event notifications are primarily used for one-way, event-based data streams where systems SEND or RECEIVE data asynchronously. You can think of these like CRUD type of requests you want to send to or receive from your connection's EHR system.

Recoverable messages

We use recoverable messages to guarantee delivery of asynchronous traffic. We save these messages into highly durable queues so that they can survive restarts or other failures. We won't respond with a 200 OK status unless we successfully saved the message in a highly durable queue first.

Read about our business continuity and disaster recovery plan.

Sequencing asynchronous events

Event notifications are delivered via Redox to the desired system using a first-in, first-out (FIFO) method. We work to maintain the order of asynchronous events in the order they're triggered.

One exception to that, though, is that Redox sometimes processes events in parallel before sending in FIFO order. So you shouldn't use the log ID to sequence requests, especially if the endpoint receives different data models or FHIR® resources. Instead, use the timestamp for when the data arrived at the endpoint to sequence it against other asynchronous traffic.

If failures happen during processing, we pause the queue for the intended endpoint so that we can maintain FIFO delivery after the issue is resolved.

Meanwhile, we send a notification to the sender or receiver, depending on where the failure occurred. Either way, the notification goes to the Alert Email, which is listed in the Organization Profile of the Redox dashboard.

Responses to SEND

Some packages don’t get to their intended destination. Amazon knows this well.

Sometimes your asynchronous messages also don’t get to their intended endpoint(s). The good news is that we can let you know whether your message arrived safely. But remember that asynchronous messages are one-way, so you won’t get a response back from your connection's system. Much like Amazon doesn’t get thank-you packages for successfully delivered orders.

Any responses to asynchronous traffic are from Redox specifically about your outgoing message. And if your message went to multiple endpoints, you receive only one overall response. Check out the details about each scenario below.

Successful response

If Redox successfully accepts your message, you receive a 200 OK status and a response body with any relevant details.

A successful status doesn't mean that the message was delivered to the intended endpoint. It only means that we received the message, saved it to a highly durable queue, and are ready to process. Then, we'll deliver it to the intended endpoint(s).

Later, if you want to know for certain whether your message was successfully processed and delivered, you can check the status of the related log. Learn more about logs.

The difference between a response and a log is that Redox sends a response to a message for multiple endpoints, but we create a log for each endpoint. So if you send one message to 10 endpoints, you receive one response with 10 log objects and IDs in Meta.Logs[].ID array (for the Data Model API).

Unsuccessful response

On occasion, Redox can’t process a request because of an issue with the request or within Redox itself. If this happens, you receive a 4XX or 5XX HTTP status code and a response with the array in the body populated: Meta.Errors[] array (for the Data Model API) or the issue[] array (for the FHIR® API). These arrays contain an error object with the type of failure and corresponding details. At a minimum, a Text field provides the error message details.

Example: Unsuccessful SEND response for the Data Model API

1
{
2
   "Meta": {
3
     …
4
     "Errors": [
5
       {
6
         "Text": "Required field missing - Device.ID in Device:New"
7
         …
8
       }
9
     ]
10
   }
11
   …
12
 }

Example: Unsuccessful SEND response for the FHIR API

1
{
2
"resourceType": "OperationOutcome",
3
"issue": [{
4
"severity": "error",
5
"code": "invalid",
6
"details": {
7
"text": "Unknown search parameter name \"foobar\" for model \"Patient\"",
8
"coding": [
9
{
10
"code": "MSG_PARAM_UNKNOWN",
11
"system": "http://terminology.hl7.org/CodeSystem/operation-outcome",
12
"display": "Parameter \"foobar\" not understood"
13
}
14
]
15
},
16
"diagnostics": "Failed to execute FHIR search"
17
}]
18
}

As for the HTTP status codes, you may see any of these:

CodeDescription
400 Bad RequestThe request is formatted incorrectly or is missing required information.
401 UnauthorizedAuthentication failed. This means you need to refresh or regenerate your access token and try again.
403 Forbidden or 404 Not FoundThe request is missing the (a) POST verb; (b) designated endpoint; or (c) specified data model/resource after api.redoxengine.com (or api.ca.redoxengine.com for Canada).
413 Payload Too LargeThe payload sent exceeds the payload size limit of 10 MB. Refer to Redox message size limits.
429 Too Many Requests Your system has exceeded the rate limit of 7,500 requests per IP address for the current five-minute rolling window. Wait a few minutes then try initiating the request again.
500 Internal Server ErrorAn unknown error occurred within Redox.
502 Bad GatewayThe request was dropped within Redox. This can sometimes occur during brief periods when internal updates are being applied.
504 Gateway TimeoutThe request took too long to complete. Requests to Redox time out after a couple of minutes.

We recommend that your system have queuing capability for your outgoing requests to Redox in case of any kind of failure. This way, your system can queue any additional outgoing requests until the issue is resolved.

Responses to RECEIVE

We rely on you to send an HTTP status code to let us know whether you successfully received a message from your connection's system. We wait for your response before deciding what to do next.

Successful receipt

If you successfully receive an event from Redox, your system should send back a 200 OK status with an empty Meta.Errors[] array (for the Redox Data Model API) or issue[] array (for the FHIR® API) in the body of the response. This response means that your system has processed the most recent data and is ready for the next payload. We proceed with sending your next asynchronous data payload.

Unsuccessful receipt

If unable to receive an event, your system should send back to Redox the relevant 4XX or 5XX HTTP status code and a response with the relevant array in the body populated: Meta.Errors[] array (for the Redox Data Model API) or the issue[] array (for the Redox FHIR® API). This array should contain an error object with the type of failure and corresponding details. At a minimum, a Text field should provide the error message details.

If you send us a failed HTTP status code in response to an asynchronous message, our next action depends on the type of environment your endpoint is in.

For a production environment, we briefly retry sending the message after a brief pause then pause the queue.

For a staging or development environment, we retry sending the message after a brief pause. But we don’t pause the queue of asynchronous messages from your connection's system.