Skip to content

Webhooks

As a case moves through BIOS, BIOS will send events to each webhook the client has registered for the event's type, or for every type. BIOS sends each event as a POST request with a JSON body.

Open questions: remove before sharing with clients

  • How long will BIOS wait for a response, and how long will it keep retrying an event?
  • Will BIOS disable an endpoint that keeps failing, and tell the client?
  • How does a client rotate its webhook's secret or its oauth2.client_secret?

Events

Event subject_type BIOS will send it when
case_sanity_checks_passed case the case's VCFs pass BIOS's sanity checks
case_sent_for_manual_review case BIOS sends the case for manual review
report_ready report the case's report is ready to download

Request

Every event has the same top-level fields. Only data differs from one event type to another.

Field Value
event_id The event's ID, which stays the same each time BIOS sends it
type The event type, such as case_sanity_checks_passed
subject_type The type of resource the event is about, such as case
subject_id The ID of the resource the event is about, such as a case_id
occurred_at When the event happened, in UTC
delivered_at When BIOS sent this request, in UTC
data The event's details, which depend on type

data includes the BIOS identifiers the client received when it created the case: case_id, order_id, proband_id and specimen_id. Events contain no patient data. For more about a case, the client can call the BIOS API.

The webhook- headers follow the Standard Webhooks specification.

Header Value
Authorization Bearer followed by an access token from the webhook's token_url
webhook-id The event's event_id
webhook-timestamp delivered_at, in seconds since the Unix epoch
webhook-signature v1, followed by the base64-encoded HMAC-SHA256 signature of the request
POST /bios/events HTTP/1.1
Host: client.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
webhook-id: evt_01kfbc3d4e5f6g7h8j9k0m1n2p
webhook-timestamp: 1794947463
webhook-signature: v1,xHUUGe+h9qd7IQunZjLcoNGTRBebkJPoTniPjrT3b6Y=

{
  "event_id": "evt_01kfbc3d4e5f6g7h8j9k0m1n2p",
  "type": "case_sanity_checks_passed",
  "subject_type": "case",
  "subject_id": "case_01kfb7q2r3s4t5v6w7x8y9z0ab",
  "occurred_at": "2026-11-17T20:31:03.120455Z",
  "delivered_at": "2026-11-17T20:31:03.402871Z",
  "data": {
    "case_id": "case_01kfb7q2r3s4t5v6w7x8y9z0ab",
    "order_id": "ord_01kfa2b3c4d5e6f7g8h9j0kmnp",
    "proband_id": "ind_01kfb7q2r3s4t5v6w7x8y9z0ac",
    "specimen_id": "spec_01kfb7q2r3s4t5v6w7x8y9z0ad"
  }
}

Verify each event

Before it acts on an event, the client should check the access token in the Authorization header, as for any other request to its API. It should also check the event's signature with the webhook's secret, and reject an old webhook-timestamp so that nobody can replay an event. A Standard Webhooks library checks the signature and webhook-timestamp. The client must pass the library the raw request body, because parsing the JSON and serializing it again can change the bytes BIOS signed.

from standardwebhooks.webhooks import Webhook, WebhookVerificationError

webhook = Webhook(WEBHOOK_SECRET)


def handle_request(body: bytes, headers: dict[str, str]) -> int:
    if not access_token_is_valid(headers):
        return 401
    try:
        event = webhook.verify(body, headers)
    except WebhookVerificationError:
        return 400
    queue_event(event)
    return 204

Webhook.verify raises WebhookVerificationError if the signature does not match, or if webhook-timestamp is more than five minutes from the current time (source, checked 2026-11-19). On success, it returns the parsed body.

Respond to each event

The client should return a 2xx response as soon as it has verified and stored the event, then process the event.

If BIOS does not receive a 2xx response, it will send the same event again, with the same event_id and a new delivered_at, until it does. BIOS will wait longer before each retry. The client may therefore receive an event more than once. The client should de-duplicate events on event_id, and skip an event whose event_id it has already processed.

Events may arrive out of order. The client should use occurred_at to order the events for a case.