Motta varsler

Sett opp et endepunkt

Du må eksponere en offentlig tilgjengelig URL som tar imot HTTPS POST-forespørsler med JSON-data, for eksempel:

https://partner.example.com/api/dps/webhook

Anbefalinger:

• Bruk IP-allowlist (vi kan oppgi faste utgående IP-er ved behov)
• Sett opp overvåkning og varsling av at tjenesten din er operativ
• Valider signaturen for hver melding før behandling

Registrer endepunktet hos Nasjonalbiblioteket

I denne fasen håndteres registrering av webhook-URL og delt hemmelig nøkkel manuelt av Nasjonalbiblioteket. Vi koordinerer oppsett og test før produksjonsbruk. Kontakt teamet for digital bevaring for å registrere endepunktet ditt.

Verifiser signaturen

Webhookene signeres for å sikre autentisitet og integritet. Mottakeren må validere signaturen før meldingen behandles. Signaturen beregnes ut fra headerne webhook-id og webhook-timestamp og rå request-body.

Pseudokode:

raw = les_rå_body()
id = header["webhook-id"]
ts = header["webhook-timestamp"]
sig_header = header["webhook-signature"]   # kan inneholde flere (v1,<b64>)

base = id + "." + ts + "." + raw
calc = base64(hmac_sha256(secret, base))

# Godta dersom én v1-signatur i header matcher calc (konstant-tids-sammenligning)
# Avvis dersom |nå - ts| > toleransevindu (replay-beskyttelse)
# Parse JSON etter vellykket verifisering

Tips: verifiser alltid signaturen mot rå request-body, ikke en reserialisert JSON-struktur.

Svar på meldingen

Webhook-mottakeren må:

• svare med HTTP 200 OK eller 204 No Content innen 10 sekunder
• returnere ingen eller minimal body (DPS bryr seg kun om statuskode)
• ved 4xx/5xx eller timeout vil DPS prøve igjen med eksponentiell backoff

Fordi DPS prøver på nytt, kan samme melding komme flere ganger. Bruk webhook-id som dedup-nøkkel.

Behandle meldingen

Bruk feltet type til å avgjøre hva du skal gjøre:

• submission.preserved: materialet er bevart. Ta vare på archiveId; du trenger den for å bestille materialet senere. Du kan nå slette kildematerialet.
• submission.rejected: innleveringen ble avvist. Listen reasons forteller hva som gikk galt, og filePath peker på filen når en feil gjelder en enkelt fil.
• dissemination.delivered: bestilt materiale er klart. Last ned filene før lenkene utløper. Se Bestille utlevering av bevart materiale.

Feltene i hver melding er listet under Webhook-hendelser.