Webhooks

Notifications Webhook

BCL provides a webhook to enable push notifications of events on your project.  This can be used to, for example, determine when new results are available. That information could then be used to query the deliverables API to fetch the result files.

This webhook is invoked whenever one of a number of specific events occurs in one of your projects.  Technical documentation, including the list of events, can be found at https://gpo.broadinstitute.org/api/redoc#tag/Webhooks.

Setup

Ask the BCL Support ([e-mail]) team to add a URL you provide to be used as a webhook. Each event will result in a separate call to this endpoint, using the POST verb.

Security

The URL you provide must start with https:// and your HTTP endpoint must have a valid TLS 1.2 or greater certificate.

While we don't expect PHI to be transmitted in this payload, they may still contain sensitive information. It is imperative that you implement appropriate security measures in your endpoint and backing systems. In addition to using a properly-encrypted endpoint, you should validate the signature of our Authorization token to ensure the message comes from BCL.

Delivery

Our delivery behavior is based on the underlying behavior of GCP pubsub push notifications with ordering keys.

Events are delivered as they occur in our system (there is no batching), so listeners should expect notifications within seconds of the event occurring, subject only to typical network and application stack latency. We will make a best-effort attempt to deliver each message in the correct sequence for each BCL order. Messages pertaining to different BCL orders may arrive in any sequence. 

Any message which is acknowledged within 30 seconds of receipt will not be delivered again. If we receive a 4xx or 5xx error response from your endpoint, we will attempt to redeliver the message for up to 7 days, after which the message will be lost.  Webhooks do not support replay.

Any undelivered message will prevent further messages from being delivered concerning the same BCL order, until the message is either delivered or expires.

Events and Statuses 

Generally, events are expected to follow the order below, however, some may be skipped depending on the order type: 

• Order Submitted: This relates to the order being successfully submitted
• Sample Kit Shipped: This relates to Direct-to-Patient (DTP) kits and the event signifies when a kit has been shipped and tracking information is available.
• Sample Received: This relates to the sample being received by BCL (unless the order is reanalysis)
• Sample Processing: This relates to the samples undergoing processing, beginning with extractions (unless the order is reanalysis)
• Sample Tech Complete: This relates to the sample status transitioning to LAB_AND_DATA_DELIVERY_COMPLETED, which means the sample has a technical sign-out, but not that data has been delivered (unless the order is reanalysis)
• Sample Interpreting:  This relates to a sample being sent for interpretation. This only applies to passing samples. The status you will see is SENT_FOR_INTERPRETATION.
• Sample Interpretation Complete: This relates to a sample completing interpretation. The status you will see is INTERPRETATION_REPORT_DELIVERED.
• Results Available: This event does not necessarily correspond to a sample or order status change. It corresponds to the "results" section of the API being populated, meaning data is available.
• Order Completed (once all results for the order are available)
• Sample Canceled: If you use the cancel endpoint to cancel a sample, this will fire the event for the samples.
• Order Canceled: If all the samples in an order are canceled, the order will be canceled as well and this event will be fired. 

Results Available is used whenever a new result and data is available, regardless of whether it is an initial delivery or a redelivery.  You can find the delivery type in the payload, under samples.*.tests.*.result_status . The initial delivery is Final. Any redeliveries are likely to appear as either Corrected or Revised.

If a sample fails in an interpretation test, the Sample Interpreting and Sample Interpretation Complete events will not be sent, but Results Available still will be.  

 

Test your Webhook Configuration

1. Provide URL to the support team at [e-mail]
2. Create an Order(s)

Use the following endpoint to create an order in the staging environment (refer to the BCL examples repo for code snippets if necessary): 

https://gpo-staging.broadinstitute.org/api/redoc#tag/Orders-and-Samples/operation/post_order_api_order_post 

You may also use this endpoint to validate order content prior to submitting to ensure all inputs are valid. 

3. Run End to End Workflow

Troubleshooting Common Issues

• Firewall/Network Issues: Ensure your endpoint is accessible from the internet and not blocked by any firewalls.
• Payload Format: Verify that your endpoint is correctly parsing the incoming payload, especially if it's in a different format than expected (e.g., XML instead of JSON). If you are receiving 400 error messages, ensure that the actual payload shape matches your modeled shape. For example, try mapping the status field to a str rather than an enum.
• Rate Limiting: Be aware of any rate limits imposed by your application receiving our webhook deliveries.
• Error Handling: Implement robust error handling in your endpoint to gracefully manage failed requests or malformed payloads.