Preview: proposed, may change

What this page describes is not live yet. Build against it together with your YOU(th) contact, who tells you when it is.

Events

What YOU(th) tells your system, and what each delivery carries.

When something happens to one of your organization's members, YOU(th) tells your system with an event: a signed POST to the HTTPS address you registered, for each event you subscribed to. A delivery says what happened and where to read it.

Events

`event_type`	Sent when	Resource
`Checkup.completed`	A member of yours completed a checkup	`Bundle` (FHIR)
`Patient.registered`	A person registered as a member of yours	`Patient` (FHIR)
`Ping.check`	You asked your YOU(th) contact for a test delivery	None

Each event type documents its own resource. New event types can appear: answer 2xx to one you do not handle.

When your integration is set up, your YOU(th) contact sets:

your webhook's address;
which events you receive;
which checkup types you receive (digital, lab, wearable, doctor). Without a restriction, every type is sent;
what a delivery carries: ids only (recommended), or ids and the resource. See What a delivery carries.

The body

Every event shares one envelope:

{  "event_id": "evt_e560fc965cf89b3d5a8c3ed27406806f",  "event_type": "Checkup.completed",  "event_version": "2",  "occurred_at": "2026-10-01T09:30:00.375000Z",  "patient_id": "cfefb422-ac79-4cb9-a849-e80f8a6f21cd",  "checkup_id": "64d866f3-0c88-485c-bfe6-3339df1d224a",  "resource_url": "https://api.example.com/v1/fhir/checkups/64d866f3-0c88-485c-bfe6-3339df1d224a"}

Field	Means
`event_id`	The event, `evt_` and 32 hex digits (`evt_ping_` and 32 for a `Ping.check`). The same on every retry: deduplicate on it
`event_type`	From the table above
`event_version`	The envelope's version, a string. Compare it exactly; a value you do not know means the envelope changed in a way that could break your receiver
`occurred_at`	When it happened, ISO 8601 in UTC
`patient_id`	The member
`checkup_id`	The checkup; only in `Checkup.completed`
`resource_url`	Where to read the resource: the checkup's bundle, or the member's `Patient`
`resource`	Only when your deliveries carry the resource: the checkup's FHIR `Bundle`, or the member's `Patient`

Patient.registered has no checkup_id; its resource_url points at the Patient.
Ping.check names no real member: its patient_id starts with test_ping_. It has no checkup_id, resource_url or resource, and uses the same envelope as every other event. Verify it, answer 2xx, and do nothing else.
Ids are opaque strings. Store them as they are; do not rely on their length or format.
New fields and new event types can appear. Ignore fields you do not know; answer 2xx to an event you do not handle.

What a delivery carries

Setting	The body holds	Your system
Ids only (recommended)	The fields above, without `resource`	Reads `resource_url` with an access token
Ids and the resource	The fields above, with `resource`	Can store the delivery as it is; reads the API only to catch up

Ids only is recommended: a delivery sent to a wrong address, or kept in a gateway's or a queue's logs, then holds no health data, and every read is checked against your client's access when it happens.
The resource is fine too: there is no extra request per event, and deliveries keep working while the read API is unavailable.
A checkup's bundle is built once, when the event happens. Every retry sends the same bundle, and reading resource_url later answers the same bundle.
A Patient in a delivery is as it was when the event happened; reading resource_url answers it as it is now.

The request


Method	`POST`, to your HTTPS address
Body	JSON, compact, keys sorted, UTF-8. Verify the raw bytes; never re-serialize
Success	Any `2xx` within ten seconds
Redirects	Not followed. A `3xx` counts as a failure that is not retried
Order	None. Deliveries can arrive in any order and more than once

Headers (their names are case-insensitive):

Header	Holds
`X-youth-event-id`	The `event_id`
`X-youth-event-type`	The `event_type`
`X-youth-event-version`	The `event_version`
`X-youth-timestamp`	When this attempt was sent, ISO 8601 in UTC
`X-youth-delivery-id`	This attempt: it changes on every retry. Do not deduplicate on it
`X-youth-delivery-attempt`	`1` for the first attempt, then `2`, `3` and so on
`X-youth-signature`	`t=<Unix seconds>,v1=<signature>`: see Verify a delivery

Not decided yet: the Content-Type of deliveries, and the value of event_version when the webhook goes live; the examples show 2. Parse the body as JSON whatever the header says, and compare event_version as a string.

Verify every delivery before you act on it, and answer fast: see Retries and duplicates.

Examples

The bodies below are pretty-printed for reading. On the wire a body is compact, with its keys sorted, as in the first example; verify the bytes as you received them.

A whole request, ids only

This request is really signed: the fixture secret on Verify a delivery verifies it.

POST /youth-webhook HTTP/1.1Host: partner.example.comX-youth-event-id: evt_e560fc965cf89b3d5a8c3ed27406806fX-youth-event-type: Checkup.completedX-youth-event-version: 2X-youth-timestamp: 2026-10-01T09:30:02ZX-youth-delivery-id: dlv_4354549c5be143f4b3e2ef0b30eccb02_1X-youth-delivery-attempt: 1X-youth-signature: t=1790847002,v1=cf7f342026cf7c2997b6af983998c8eb9c9e3c5deb2e84cc9adab60948caf378{"checkup_id":"64d866f3-0c88-485c-bfe6-3339df1d224a","event_id":"evt_e560fc965cf89b3d5a8c3ed27406806f","event_type":"Checkup.completed","event_version":"2","occurred_at":"2026-10-01T09:30:00.375000Z","patient_id":"cfefb422-ac79-4cb9-a849-e80f8a6f21cd","resource_url":"https://api.example.com/v1/fhir/checkups/64d866f3-0c88-485c-bfe6-3339df1d224a"}

`Checkup.completed` with the resource

The same body, with the checkup's bundle in resource. Shortened here: FHIR has the whole bundle.

{  "event_id": "evt_e560fc965cf89b3d5a8c3ed27406806f",  "event_type": "Checkup.completed",  "event_version": "2",  "occurred_at": "2026-10-01T09:30:00.375000Z",  "patient_id": "cfefb422-ac79-4cb9-a849-e80f8a6f21cd",  "checkup_id": "64d866f3-0c88-485c-bfe6-3339df1d224a",  "resource_url": "https://api.example.com/v1/fhir/checkups/64d866f3-0c88-485c-bfe6-3339df1d224a",  "resource": {    "resourceType": "Bundle",    "id": "90970514-fbcb-4c07-aee3-3778f4dc594a",    "type": "collection",    "timestamp": "2026-10-01T09:30:00Z",    "entry": [      {        "fullUrl": "urn:uuid:c47f1291-702c-42a1-a0f6-bbf4cb4eee15",        "resource": {          "resourceType": "Observation",          "id": "119d03ca-128d-4a26-8924-fa76fa92fbfe",          "status": "final",          "code": {            "coding": [              { "system": "https://example.com/fhir/CodeSystem/biomarkers", "code": "heart_rate" }            ]          },          "subject": { "reference": "urn:uuid:797790be-4a7b-4aeb-a554-e2685ee57942" },          "effectiveDateTime": "2026-10-01T09:24:00Z",          "valueQuantity": {            "value": 64,            "unit": "bpm",            "system": "http://unitsofmeasure.org",            "code": "/min"          }        }      }    ]  }}

`Patient.registered`, ids only

{  "event_id": "evt_3b9e0f6a1c2d4e5f8a7b6c5d4e3f2a1b",  "event_type": "Patient.registered",  "event_version": "2",  "occurred_at": "2026-10-01T08:12:40.120000Z",  "patient_id": "cfefb422-ac79-4cb9-a849-e80f8a6f21cd",  "resource_url": "https://api.example.com/v1/fhir/Patient/cfefb422-ac79-4cb9-a849-e80f8a6f21cd"}

`Ping.check`

{  "event_id": "evt_ping_9f1c2b7e4d3a4c5b8e6f0a1b2c3d4e5f",  "event_type": "Ping.check",  "event_version": "2",  "occurred_at": "2026-10-01T09:00:00.000000Z",  "patient_id": "test_ping_4a7c9e21"}

Events

Events

The body

What a delivery carries

The request

Examples

A whole request, ids only

Checkup.completed with the resource

Patient.registered, ids only

Ping.check

`Checkup.completed` with the resource

`Patient.registered`, ids only

`Ping.check`