Quickstart
Receive a test event, verify it, and read a checkup's FHIR bundle.
This walks through an integration end to end: a test delivery reaches your receiver, your receiver checks it is from YOU(th), and your backend reads a checkup. You need the three secrets your YOU(th) contact gives you, kept on your server:
| Variable | Holds |
|---|---|
YOUTH_CLIENT_ID | Your integration's client id |
YOUTH_CLIENT_SECRET | Its client secret, to get tokens |
YOUTH_WEBHOOK_SECRET | The secret your deliveries are signed with |
1. Receive a delivery
Give your YOU(th) contact an HTTPS address for your receiver, and ask for a test delivery. YOU(th)
sends a Ping.check event: signed like every other delivery, and naming no real member.
import { createServer } from "node:http";import { verifyDelivery } from "./verify-delivery";createServer((request, response) => { const chunks: Buffer[] = []; request.on("data", (chunk: Buffer) => chunks.push(chunk)); request.on("end", () => { const body = Buffer.concat(chunks); const signed = verifyDelivery( process.env.YOUTH_WEBHOOK_SECRET ?? "", String(request.headers["x-youth-signature"] ?? ""), body, ); response.writeHead(signed ? 200 : 401).end(); if (signed) console.log(JSON.parse(body.toString("utf8")).event_type); });}).listen(8080);2. Verify it
verifyDelivery is on Verify a delivery. It checks the signature over the
raw body, exactly as it arrived, and refuses a delivery more than five minutes old. Your receiver
logs Ping.check once it works. A Ping.check needs nothing more: answer 2xx, and do nothing
else with it.
3. Read a checkup
When a member completes a checkup, YOU(th) sends Checkup.completed, with the address of the
checkup's bundle in resource_url. Get a token, then read it:
TOKEN=$(curl --silent https://auth.example.com/oauth2/token \ --data grant_type=client_credentials \ --data client_id="$YOUTH_CLIENT_ID" \ --data client_secret="$YOUTH_CLIENT_SECRET" | jq --raw-output .access_token)curl https://api.example.com/v1/fhir/checkups/64d866f3-0c88-485c-bfe6-3339df1d224a \ --header "Authorization: Bearer $TOKEN"The answer is the checkup as a FHIR Bundle: the member, the checkup and every measurement. See
FHIR.
Next
- Answer fast and take each delivery once: Retries and duplicates.
- Know every event and what it carries: Events.
- List what you missed while your receiver was down: Catch up after an outage.