Veilig koppelen, van sleutel tot postback.

Authenticatie & sleutels

• De API-key blijft op je server. Hij wordt één keer getoond en werkt namens je account. Bewaar hem versleuteld, buiten browsercode, logs en URL's. Stuur hem alleen als Authorization: Bearer {api_key} mee.
• Geef een key alleen de rechten die je nodig hebt. Een nieuwe key krijgt standaard workflows:read, sessions:create en sessions:read; je kunt ze bij het aanmaken beperken.
• Staging en productie zijn gescheiden. Je test met een stagingkey. Een productiekey volgt pas na de gezamenlijke acceptatie.
• De gehoste link is een geheim. redirect_url geeft toegang tot één sessie en verloopt na 72 uur. Het deel na # is het eenmalige toegangsdeel: open de link precies zoals je hem krijgt en kort hem nooit in, log hem niet en laat hem niet indexeren.
• Elk postback_secret hoort bij één sessie. Bewaar het versleuteld bij je eigen referentie, net als de key.

HMAC & replay-preventie

• Controleer de handtekening vóór je de JSON leest. Hysio ondertekent de onbewerkte body met HMAC-SHA256. Bereken de waarde over exact de ontvangen bytes en vergelijk in constante tijd met X-Hysio-Signature. Voorbeelden in Python, Node.js en PHP staan in stap 05 van de Quickstart.
• Headers helpen zoeken, niet vertrouwen. Met X-Hysio-Session en X-Hysio-Idempotency-Key vind je de juiste sessie en het juiste geheim in je eigen opslag. Ze vervangen de handtekeningcontrole niet.
• Verwerk elke postback één keer. De handtekening bevat geen tijdstempel. Herken een herhaalde of opnieuw bezorgde postback aan session_id en negeer een tweede exemplaar.
• Antwoord direct met 2xx. Sla een geldige postback eerst duurzaam op en antwoord daarna, zonder redirect.

Netwerk & SSRF-regels

Hysio roept je postback_url zelf aan. Daarom gelden er vaste regels voor dat adres:

• Alleen HTTPS en een publiek adres. Een adres op een privaat, loopback-, link-local of ander gereserveerd netwerk wordt geweigerd, als IPv4 of IPv6, als letterlijk IP-adres of via een hostnaam. Elk adres waar de hostnaam naar verwijst telt mee.
• Twee keer gecontroleerd. Hysio controleert het adres bij het starten van de sessie en opnieuw vlak voor elke bezorging, omdat DNS in de tussentijd kan veranderen.
• Geen redirects. Hysio volgt geen doorverwijzing. Gebruik het definitieve adres van je endpoint.
• Zelf afschermen mag. Een eigen firewall of WAF voor het endpoint blijft jouw keuze; de handtekening blijft de echte controle.

Dataminimalisatie

• Test met fictieve gegevens. Op staging gebruik je nooit echte patiënt- of cliëntgegevens.
• Geen persoonsgegevens in technische velden. Een Idempotency-Key, je eigen referentie en je postback_url zijn ondoorzichtige waarden. Zet er geen naam, geboortedatum of BSN in.
• Stuur alleen wat de werkstroom nodig heeft. Laat velden weg die geen rol spelen in het verslag.
• Productie pas na afspraken. Echte gegevens verwerk je pas na de gezamenlijke acceptatie en met een verwerkersovereenkomst.

Hosting & TrustCentre