Skip to content

Register a webhook

A client registers an HTTPS endpoint to receive webhook events.

Register the webhook

The client should send a new UUID in the Idempotency-Key header, and the same key if it retries the request, so that a retry does not register the webhook twice. url must begin with https://.

IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST https://sandbox.biosgenomics.com/api/v1/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: \"$IDEMPOTENCY_KEY\"" \
  -H "Content-Type: application/json" \
  -d @webhook.json
webhook.json
{
  "url": "https://client.example.com/bios/events",
  "event_types": [], // (1)!
  "description": "All BIOS events",
  "oauth2": {
    "token_url": "https://auth.client.example.com/oauth/token",
    "client_id": "bios-webhooks",
    "client_secret": "your-client-secret",
    "scope": "bios.events.write" // (2)!
  }
}
  1. Leave event_types empty to receive every event type, including any BIOS adds later. To receive only some event types, list them:

    "event_types": [
      "case_sanity_checks_passed",
      "report_ready"
    ]
    
  2. scope is optional.

oauth2 lists the OAuth 2.0 client credentials BIOS will use to call url. Before it sends an event, BIOS will get an access token from token_url with the client credentials grant, and send the token in the event's Authorization header. BIOS will reuse the token until it expires.

Response

The BIOS API returns 201 with the webhook. The client must store secret to verify each event BIOS sends. The BIOS API returns secret only in this response. It never returns oauth2.client_secret.

{
  "webhook_id": "wh_01kfb6a7b8c9d0e1f2g3h4j5k6",
  "organization_id": "org_01kf9c8d7e6f5g4h3j2k1m0npq",
  "url": "https://client.example.com/bios/events",
  "event_types": [],
  "description": "All BIOS events",
  "oauth2": {
    "token_url": "https://auth.client.example.com/oauth/token",
    "client_id": "bios-webhooks",
    "scope": "bios.events.write"
  },
  "status": "enabled",
  "secret": "whsec_W3OCtApeCOYH8NZh59rY0XJqEtrhk4LjcR6z/OO3uIs=",
  "created_at": "2026-11-17T19:40:11.530188Z",
  "updated_at": "2026-11-17T19:40:11.530188Z"
}