Handling notifications and responses

Notifications are for one-way, event-based data streams where systems either SEND or RECEIVE data asynchronously. Think of these as CRUD-style requests you want to send to or receive from your connection.

Redox delivers notifications to the destination using a first-in, first-out (FIFO) method. We work to maintain the order of asynchronous notifications in the order they’re triggered.

An exception to FIFO is that Redox sometimes processes events in parallel before sending. For this reason, you shouldn’t use the log ID to sequence requests, especially if the destination is part of multiple subscriptions. Instead, use the timestamp for when the data arrived at the destination to sequence it against other asynchronous traffic.

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

We send a notification to the source or destination system, 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. Learn more about checking Redox system alerts.

For non-critical errors, you can avoid automatic queue pausing by sending back a 200 OK status:

• before performing data validation; or
• after finding a minor error that can be resolved later.

Track these non-critical errors in your system and submit a request to our Help Center if you need help resolving.

This best practice helps to:

• prevent unnecessarily pausing production traffic;
• allows your development/staging traffic to proceed with business as usual; and
• ensures continuity in your data delivery so that your traffic doesn’t get stalled for one troublesome log.

If you identify a critical error or you’re experiencing downtime, we recommend sending a 4XX or 5XX status to Redox. We’ll pause your queue so that none of your data is lost while you work to resolve your system.

When handling asynchronous notifications, it’s important to understand two different response scenarios:

1. Response from Redox (after you SEND): This is the immediate acknowledgement Redox sends to you after you send a notification. It confirms whether Redox successfully received your message for processing.

   Recoverable messages

   Redox uses 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.

2. Response to Redox (when you RECEIVE): This is the acknowledgment you must send to Redox after receiving a notification from your connection. Your response tells Redox whether you successfully processed the message.

When you send a notification, Redox responds to say whether your notification was accepted for processing and delivery. This would be like the Post Office sending a note to say they received and are ready to deliver a package you sent.

Since notifications are one-way traffic, you won’t get a response from your connection. Any responses to your outgoing asynchronous traffic are specifically from Redox about the processing of the notification.

If your notification went to multiple destinations, you only receive one overall response from Redox.

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

A success response means that Redox:

• received the notification;
• saved the notification to a highly durable queue; and
• is ready to process and deliver the notification.

Note that this doesn’t mean the notification was delivered to the intended destination yet. Check the status of the related log later on to see whether your notification was successfully processed and delivered. Learn more about logs.

A log is created for every destination you send to. However, if one notification is sent to multiple destinations, you only receive one response from Redox. For example, if you send a notification to 10 destinations, you receive one Redox response with 10 log objects and IDs.

On occasion, Redox can’t process a notification because of an issue with the request or within Redox. If this happens, we respond with a 4XX or 5XX HTTP status code (review HTTP statuses). The body of the response contains a populated errors array:

• Meta.Errors[] array (for the Data Model API)
• issue[] array (for the FHIR® API)

The error or issue array contains an object with the type of failure and corresponding details. At a minimum, a Text field provides the error message details.

In the event of an error, you can initiate a manual retry. We also recommend that you have queuing capability for your outgoing traffic to Redox. That way, your system can queue any additional traffic until the issue is resolved.

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

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
}

When you receive a notification, you must respond to Redox to say whether you successfully received it. We wait for your response before deciding what to do next.

If you successfully receive a notification from Redox, you should respond with a 200 OK status and a response body with any relevant details.

A success response means that your system has processed the most recent notification and is ready for more. We proceed with sending your next notification.

If there’s a critical error with the request or within your system, you should respond with the relevant 4XX or 5XX HTTP status code (review HTTP statuses). The body of the response should contain a populated errors array:

• Meta.Errors[] array (for the Redox Data Model API)
• issue[] array (for the FHIR® API)

The error or issue array should contain an object with the type of failure and corresponding details. At a minimum, a Text field should provide the error message details.

If you respond with a failed HTTP status code, our next action depends on the type of environment your destination is in:

• Production environment: We wait a few seconds before automatically retrying to send the notification. We also pause the queue until the notification succeeds. Learn more about automatic retries.
• Staging or development environment: We don’t automatically retry the failed message or pause the queue. Talk with your connection if you need them re-send the notification.