Je eerste sessie. Van toegang tot postback.

01. Omgeving en toegang

Test altijd eerst op staging, met fictieve gegevens.

Vraag een testaccount aan via de contactpagina. Daarna maak je in de Hysio-app een API-key aan. Een nieuwe key krijgt standaard drie rechten; je kunt ze bij het aanmaken beperken:

• workflows:read om werkstromen te ontdekken;
• sessions:create om sessies te starten en bij te sturen;
• sessions:read om sessies en resultaten te lezen.

De key wordt één keer getoond en werkt namens je account. Bewaar hem versleuteld op je server, buiten browsercode, logs en URL's. Stuur bij elke aanroep Authorization: Bearer {api_key} en Accept: application/json mee.

02. Ontdek de werkstroom en de uitvoer

Lees de werkstroom-ID uit de catalogus. Bouw niet tegen een vaste voorbeeld-ID uit een PDF of deze gids.

GET {base_url}/workflows
Authorization: Bearer {api_key}
Accept: application/json

GET {base_url}/workflows/{workflow_id}
Authorization: Bearer {api_key}
Accept: application/json

GET {base_url}/workflows/{workflow_id}/questions
Authorization: Bearer {api_key}
Accept: application/json

GET {base_url}/workflows/{workflow_id}/available-responses
Authorization: Bearer {api_key}
Accept: application/json

• /workflows/{workflow_id} geeft de stappen in vaste volgorde. Die volgorde heb je nodig voor directe verwerking.
• /questions geeft de werkstroomvragen met hun api_name, of ze verplicht zijn en welk invoertype ze hebben.
• /available-responses geeft default_layout en de layouts met nummer, naam en structuur. Gebruik die structuur voor je veldmapping.

Een lege lijst bij available-responses betekent niet altijd dat er geen JSON komt. Bij sommige werkstromen is JSON op een oudere manier ingesteld. Controleer daarom na afronding altijd output_json_status.

03. Start een sessie

Gehoste sessie

Je server start de sessie en geeft de teruggekregen link aan de zorgprofessional. Je postbackadres moet een publiek HTTPS-adres zijn.

POST {base_url}/workflows/{workflow_id}/hosted-session
Authorization: Bearer {api_key}
Accept: application/json
Content-Type: application/json
Idempotency-Key: partner-staging-test-001

{
  "postback_url": "https://partner.example/hysio/postback",
  "collect_answers": true
}

Met collect_answers: true beantwoordt de zorgprofessional de werkstroomvragen in Hysio. Laat je die waarde weg of zet je haar op false, stuur dan zelf answers mee, met de api_name van elke vraag als sleutel.

{
  "message": "Hosted session created successfully.",
  "session_id": 1841,
  "redirect_url": "https://app.staging.server03.hysio.nl/hosted/1841#…",
  "expires_at": "2026-10-06T10:00:00+00:00",
  "postback_secret": "{postback_secret}",
  "awaits_answers": true
}

• Bewaar session_id, expires_at en postback_secret versleuteld bij je eigen referentie.
• Open redirect_url precies zoals je hem krijgt, inclusief het deel na #. Wijzig of verkort de link niet.
• De link geeft toegang tot deze ene sessie en verloopt na 72 uur. Behandel hem als een geheim.

Een herhaalde aanvraag met dezelfde Idempotency-Key binnen 24 uur geeft dezelfde respons terug, met hetzelfde geheim en dezelfde link. Er ontstaat dan geen tweede sessie.

Directe verwerking

Lees eerst de stappen van de werkstroom. De array steps bevat precies één invoerblok per stap, in dezelfde volgorde. Vul verplichte werkstroomvragen in answers in. Het voorbeeld past bij een werkstroom met één stap en zonder verplichte vragen.

POST {base_url}/workflows/{workflow_id}/run
Authorization: Bearer {api_key}
Accept: application/json
Content-Type: application/json
Idempotency-Key: partner-staging-direct-001

{
  "answers": {},
  "steps": [
    {"input": "Fictieve gesprekstekst voor de eerste stap."}
  ]
}

De aanvraag verwerkt alle stappen in één keer en geeft het verslag in Markdown terug. De huidige code antwoordt met 201, het contract noemt 200. Accepteer beide en controleer de inhoud van de respons. JSON is direct na de run meestal nog pending; lees die daarna via de uitvoer.

04. Lees status en resultaat

GET {base_url}/sessions/{session_id}
Authorization: Bearer {api_key}
Accept: application/json

GET {base_url}/sessions/{session_id}/output
Authorization: Bearer {api_key}
Accept: application/json

Een sessie is in_progress, completed of cancelled. Vraag je de uitvoer op voordat de sessie klaar is, dan krijg je 409 met de actuele status. De uitvoer bevat output (Markdown), output_json, output_json_status en layout.

Gebruik alleen een beschikbaar layoutnummer. Geeft /available-responses layouts terug, kies dan één nummer en vraag de uitvoer steeds op met ?layout={layout_number}. Is de lijst leeg, laat de query weg en beoordeel output_json_status; stem een eventueel ouder JSON-profiel af voordat je daarop een mapping bouwt. Verzin geen layoutnummer: een onbekend nummer geeft 404.

Een aanvraag met een andere beschikbare layout maakt een nieuwe JSON-weergave en vervangt de opgeslagen JSON. De uitvoer zonder layout, de sessie en een opnieuw verstuurde postback bevatten daarna die laatst gekozen JSON-weergave. Controleer het veld layout in de /output-respons; de sessierespons en postback vermelden dat nummer niet afzonderlijk.

Een afgeronde sessie garandeert geen bruikbare JSON. Het Markdown-verslag is altijd het leidende resultaat.

05. Controleer de postback

Bij een gehoste sessie stuurt Hysio na afronding een postback naar je postback_url. Hysio ondertekent de onbewerkte requestbody met HMAC-SHA256 en het postback_secret van die sessie. De handtekening staat in de header X-Hysio-Signature, als sha256= gevolgd door de hexwaarde.

Controleer de handtekening over de bytes zoals je ze ontvangt, vóór je de JSON leest. JSON eerst parsen en opnieuw opbouwen verandert de bytes en breekt de controle.

Kies je taal. Beide voorbeelden doen precies hetzelfde.

import hashlib
import hmac
import json

def verify_postback(raw_body: bytes, signature: str,
                    postback_secret: str) -> dict:
    expected = "sha256=" + hmac.new(
        postback_secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(expected, signature):
        raise ValueError("Ongeldige handtekening")
    return json.loads(raw_body)

# raw_body = de exacte ontvangen bytes, vóór JSON-parsing
# signature = waarde van de header X-Hysio-Signature
# postback_secret = het veilig opgeslagen geheim van deze sessie

const crypto = require("node:crypto");

function verifyPostback(rawBody, signature, postbackSecret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", postbackSecret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(String(signature || ""), "utf8");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    throw new Error("Ongeldige handtekening");
  }
  return JSON.parse(rawBody.toString("utf8"));
}

// rawBody = Buffer met de exacte ontvangen bytes, vóór JSON-parsing
// signature = waarde van de header X-Hysio-Signature

Werk je in PHP? Lees de body met file_get_contents('php://input') vóór elke parsing, bereken 'sha256=' . hash_hmac('sha256', $rawBody, $postbackSecret) en vergelijk met hash_equals($expected, $signature). Gebruik nooit == voor die vergelijking.

• Kies het juiste geheim via je eigen registratie van de sessie. De headers X-Hysio-Session en X-Hysio-Idempotency-Key helpen bij het opzoeken, maar vervangen de handtekeningcontrole niet.
• Controleer na verificatie session_id, de werkstroom en je eigen referentie voordat je iets aan een dossier koppelt.
• Sla een geldige postback duurzaam op en antwoord daarna met een 2xx-status.
• De handtekening bevat geen tijdstempel. Herken een herhaalde of opnieuw bezorgde postback aan session_id en verwerk hem één keer.
• Hysio volgt geen redirects. Gebruik het definitieve adres van je endpoint als postback_url.

De velden van de postback zie je in het fictieve voorbeeld bij Dossierovername.

06. Herhalen, fouten en limieten

Veilig herhalen

De drie startroutes (/run, /start en /hosted-session) accepteren een Idempotency-Key van maximaal 255 tekens.

• Gebruik één eigen, ondoorzichtige waarde per nieuwe sessie, bijvoorbeeld je interne recordnummer. Zet er geen persoonsgegevens in.
• Herhaal je binnen 24 uur dezelfde aanvraag met dezelfde key, dan krijg je de eerste geslaagde respons terug met de header Idempotency-Replayed: true.
• Die herhaling kijkt alleen naar de key, niet naar de inhoud. Stuur je met dezelfde key andere inhoud, dan wordt die niet verwerkt en krijg je de eerste respons terug. Gebruik voor een nieuwe sessie dus altijd een nieuwe key.
• Loopt er nog een aanvraag met dezelfde key, dan krijg je 409. Een lopende aanvraag houdt de key maximaal 300 seconden vast. Wacht en probeer het daarna opnieuw met dezelfde key.
• Alleen geslaagde antwoorden worden bewaard. Na een 4xx of 5xx kun je dezelfde key opnieuw gebruiken.

Invoer op een losse stap (/input) heeft geen idempotency. Herhaal die niet blind.

Foutcodes

Bezorging van de postback

De postbackjob doet in de huidige code maximaal vijf pogingen, met tussenpozen van 1 minuut, 5 minuten, 15 minuten en 1 uur. Een nieuwe poging volgt bij een 4xx- of 5xx-antwoord of een verbindingsfout. Dit is een code-instelling, geen bezorggarantie. Komt er niets binnen, lees dan de uitvoer zelf of vraag een nieuwe bezorging aan met POST /sessions/{session_id}/postback/resend. Dat antwoordt met 202.

Limieten en contractversie

• De drie startroutes zijn begrensd op 10 aanvragen per minuut, opnieuw bezorgen op 6 per minuut.
• Het contract is OpenAPI 3.1, versie 1.0.0. Leg voor je eigen integratie ook de ophaaldatum en een hash van het contract vast, omdat het versienummer alleen niet elke wijziging toont.
• De integratiegids (PDF) gebruikt productie-URL's in zijn voorbeelden, ook in de stagingversie. Test altijd met de staging-basis-URL uit stap 01.

07. Als het niet lukt