How do I set up webhooks in the ROOK Portal? | ROOK : One infrastructure for continuous health data — connecting wearables, medical devices, EHRs, labs, and more through one simple API.

ROOK pushes data and status to your integration through webhooks, configured in Setup → Webhook in the ROOK Portal. Four tabs are configured independently for each Client and environment: Data Webhook for user summaries and health events, Notification Webhook for integration status, Basic Auth if your endpoint requires credentials, and Signature to verify a delivery came from ROOK.

What are the four webhook tabs in the ROOK Portal?

Tab	What it delivers	Plan
Data Webhook	User summaries and health events.	All plans
Notification Webhook	Integration status only — no health data.	Add-on
Basic Auth	Adds credentials to every delivery, for endpoints that require them.	Add-on
Signature	Lets you verify a delivery really came from ROOK.	All plans

Each tab is configured per environment, so your Sandbox endpoint and your Production endpoint are independent settings.

How do I set up my Data Webhook?

Set the URL where ROOK sends event data, then select Test webhook. ROOK sends a sample payload immediately and returns one of three results:

Result	What it means
Delivered	Your endpoint accepted the payload.
Non-2xx status	Your endpoint answered, but not with a status ROOK accepts as delivered.
No response	Your endpoint never answered. Check that the URL is public and reachable from the internet, not only from your local network — the usual causes are DNS, TLS or a timeout.

In Sandbox, the ROOK Portal shows a guide to a public testing URL (for example, webhook.site) next to the form, since your real endpoint is usually not reachable yet while you are building.

What happens if my endpoint is down when ROOK sends a delivery?

ROOK accepts a delivery only when your endpoint answers 200, 201 or 202. On any other status, or no answer at all, ROOK retries up to 3 more times and then stops trying that payload.

Attempt	Timing
Original delivery	immediately
Retry 1	2 hours
Retry 2	24 hours
Retry 3	48 hours

To recover deliveries your endpoint missed over a period, the ROOK API has an endpoint that requests a resend for a given time window. See the ROOK API Reference.

What is the Notification Webhook, and which events can I receive?

The Notification Webhook is a separate endpoint that receives integration status only — it never carries user health data. You choose which event types to receive:

Event	Fires when
`user_created`	a new end user is registered
`user_connected`	a user links a wearable or health account
`user_disconnected`	a user unlinks a source, or revokes access
`user_data_extraction`	ROOK could not extract a user's data (expired token, source down, and similar)
`webhook_send_data`	your Data Webhook rejected a delivery

The event type list stays locked until you save an endpoint URL on this tab first.

When do I need Basic Auth on my webhook?

Turn on Basic Auth only if your own endpoint rejects unauthenticated requests. Most endpoints do not. Set a username and password in the ROOK Portal, and ROOK sends them as a standard Authorization: Basic header on every delivery:

Authorization: Basic base64(username:password)

How do I verify that a webhook delivery really came from ROOK?

Every ROOK delivery carries an X-ROOK-HASH header. Reveal your signing key on the Signature tab — shown once per reveal, masked otherwise — and recompute the hash from three values concatenated in this order: your Client UUID, the user_id, and metadata.datetime_string from the payload. That field is an ISO 8601 string; use it exactly as it appears in the JSON, without re-parsing it.

python

import hmac import hashlib  message = f"{client_uuid}{user_id}{metadata_datetime_string}"  expected = hmac.new(     signing_key.encode("utf-8"),     message.encode("utf-8"),     hashlib.sha256, ).hexdigest()  is_valid = hmac.compare_digest(expected, received_hash)

If the hash does not match, discard the payload. Treat the signing key like any other secret: never paste it into a ticket, a chat, a screenshot or a public repository.

Frequently asked questions

Why isn't my signing key showing? You have not generated one yet for this Client and environment. Reveal it once on the Signature tab and store it like any other secret.