Zum Hauptinhalt springen

Webhooks

Statt regelmäßig mit changedSince nachzufragen, kann die USP deinem System jede Änderung an einem Fall aktiv melden: als POST mit einem JSON-Umschlag an eine Adresse, die du vorgibst. Ein Webhook sagt dir, dass und was ungefähr sich geändert hat. Die Details liest du danach wie gewohnt über die API v1 nach.

:::info Abos richtet der Betreiber ein Webhook-Abos werden nicht über /api/external/v1 verwaltet, sondern von den Administrator:innen des Betreibers. Für ein Abo brauchen sie von dir:

  • die Ziel-URL (nur https:// und öffentlich erreichbar — an interne oder private Adressen stellt die USP nicht zu, und Weiterleitungen folgt sie nicht),
  • das Anmeldeverfahren samt Zugangsdaten (siehe Anmeldung),
  • die Ereignisarten, die du empfangen willst,
  • optional einen Standortfilter innerhalb deines Mandanten.

Ein neues Abo startet angehalten und wird erst in einem eigenen Schritt scharfgeschaltet — in der Regel nach einem erfolgreichen Testruf (ping). Ereignisse, die entstehen, solange das Abo angehalten ist, gehen nicht verloren — sie kommen nach dem Scharfschalten in Reihenfolge. :::

Der Umschlag​

Jedes Ereignis kommt im selben Umschlag an; nur data hängt von der Ereignisart ab.

:::tip Maschinenlesbar Umschlag, Ereignisarten, data je Ereignis, Header und Antwortcodes stehen auch in der OpenAPI-Spezifikation der API v1 — als Abschnitt webhooks (OpenAPI 3.1), in der Swagger-UI unter <host>/api-docs (Gruppe „Externe API v1") unterhalb der Endpunkte. Daraus lassen sich Typen für deinen Empfänger generieren; je Ereignisart gibt es ein eigenes Schema (z. B. WebhookAttachmentCreatedEvent). :::

{
"specVersion": "1",
"eventId": "6f1c2d9e-3b8a-4c57-9a0e-2d4b7c1e8f30",
"eventType": "attachment.created",
"occurredAt": "2026-11-10T14:05:07.412+01:00",
"sequence": 48211,
"subscriptionId": "3b9f0c6a1d2e4f5a8b7c6d5e4f3a2b1c",
"tenantRoot": "musterhaus",
"caseId": "0b8e4a52-7c1d-4e2f-9a3b-5c6d7e8f9a0b",
"actor": {
"channel": "APP",
"username": "m.mustermann",
"apiAuthored": false,
"keyId": null
},
"case": {
"id": "0b8e4a52-7c1d-4e2f-9a3b-5c6d7e8f9a0b",
"status": "RELEASED",
"opened": "2026-11-03T09:12:44.000+01:00",
"updated": "2026-11-10T14:05:07.000+01:00",
"caseHandler": "linkki",
"fileSign": "AZ-2026-0815",
"externalIdPartner": "CLM-77812"
},
"data": {
"attachmentId": "7f3c2a10-5b4e-4d6a-9c1e-2b8f0a4d6e91",
"fileName": "vollmacht.pdf",
"created": "2026-11-10T14:05:07.000+01:00",
"tag": "POA",
"signable": true
}
}
FeldBedeutung
specVersionVersion des Umschlags. Heute "1".
eventIdKennung des Ereignisses. Dein Dublettenschlüssel — eine erneute Zustellung desselben Ereignisses trägt dieselbe eventId.
eventTypeEreignisart, siehe Ereignisse.
occurredAtWann die Änderung passiert ist.
sequenceFortlaufende Nummer, je Fall streng steigend, mit Lücken (die Nummer ist über alle Fälle vergeben). Daran stellst du die Reihenfolge wieder her.
subscriptionIdKennung des Abos, über das die Zustellung läuft.
tenantRootMandant des Abos.
caseIdDer betroffene Fall.
actorWer die Änderung ausgelöst hat, siehe unten.
caseDer Fallrahmen, siehe unten.
dataEreignisspezifische Angaben, siehe Ereignisse.

Allgemeine Regeln:

  • Alle Zeitstempel sind ISO 8601 mit Versatz und drei Nachkommastellen (2026-11-10T14:05:07.412+01:00).
  • Felder ohne Wert fehlen, statt null zu sein. Die einzige Ausnahme ist actor.keyId.
  • Unbekannte Felder ignorierst du — der Umschlag darf wachsen. Ebenso unbekannte Werte in status, channel oder tag.
  • Kein Freitext. Weder Kommentartext noch Unfallhergang noch Stornobegründung verlassen die USP über einen Webhook. data enthält Feldnamen, Kennungen und Aufzählungswerte.

actor​

FeldBedeutung
channelÜber welche Fläche die Änderung kam: APP, API, PARTNER, PORTAL (die Kund_in — Kundenportal oder Signatur-Link) oder SYSTEM (auch, was die Plattform selbst im Zuge einer Kund_innen-Aktion tut, etwa die automatisch erzeugte Vollmacht). Behandle Unbekanntes wie SYSTEM.
usernameWer gehandelt hat. Über die API ist das der technische Benutzer deines Mandanten.
apiAuthoredtrue, wenn die Änderung über die externe API kam.
keyIdÖffentliche ID des API-Schlüssels, falls einer beteiligt war — sonst ausdrücklich null. Daran erkennst du deine eigenen Schreibzugriffe.

Der Fallrahmen case​

Damit du ein Ereignis ohne Rückfrage einordnen kannst, wiederholt jeder Umschlag die wichtigsten Felder des Falls: id, status, opened (Anlage), updated (letzte Änderung), caseHandler, fileSign (Aktenzeichen) und externalIdPartner (deine Fall-ID, falls gesetzt).

:::caution Der Rahmen ist der Stand beim Senden case wird erst beim Zustellen gelesen, nicht beim Ereignis. Zwei Zustellungen derselben eventId können deshalb verschiedene Rahmenwerte tragen. Vergleiche Dubletten über die eventId, nie über den Rumpf. Was zum Zeitpunkt des Ereignisses galt, steht in data. :::

externalIdPartner gilt für den ganzen Mandanten. Eine Änderung nur dieses Felds erzeugt kein eigenes Ereignis; der Rahmen trägt den neuen Wert beim nächsten Ereignis mit.

Ereignisse​

eventTypeWanndata
case.status.changedDer Status eines Falls wechselt.status, previousStatus; bei CANCELLED zusätzlich hasCancellationReason
case.changedFallfelder werden geändert — auch beim Anlegen eines Falls.changedFields
party.changedAngaben zu einer beteiligten Person werden geändert.party, changedFields
evaluation.values.changedRegulierungswerte werden erfasst oder geändert.reason, changedFields
case.tag.changedEin Fall-Etikett wird gesetzt oder entfernt.tag, reason
comment.createdEin Kommentar wird geschrieben.siehe Kommentare
comment.updatedEin Kommentar wird bearbeitet.siehe Kommentare
attachment.createdEin Dokument wird hochgeladen oder erzeugt.attachmentId, fileName, created, tag, signable
attachment.deletedEin Dokument wird gelöscht.attachmentId, fileName, tag
attachment.tag.changedDas Etikett eines Dokuments wird gesetzt, geändert oder entfernt.attachmentId, tag, previousTag, reason
case.locations.changedAbonnierbar, wird derzeit noch nicht erzeugt.—
pingTestruf aus der Verwaltung und stündlich als Lebenszeichen.sentAt

Fall und Beteiligte​

  • case.status.changed — status ist der Status, in den der Fall mit diesem Ereignis gewechselt ist, previousStatus der vorherige (fehlt, wenn es keinen gab). Nimm den Status aus data, nicht aus dem Fallrahmen: wechselt ein Fall zweimal kurz hintereinander, zeigt case.status in beiden Ereignissen schon den jüngsten Stand. Ein Speichern ohne Statuswechsel erzeugt kein Ereignis. Bei einer Stornierung sagt hasCancellationReason nur, ob eine Begründung vorliegt — den Text liest du über die API.

    "data": { "status": "CANCELLED", "previousStatus": "RELEASED", "hasCancellationReason": true }
  • case.changed — changedFields nennt die geänderten Felder in snake_case, ohne Werte. Mehrere Änderungen am selben Fall innerhalb von 10 Sekunden werden zu einem Ereignis zusammengefasst; changedFields ist dann die Vereinigung (siehe Zusammenfassen).

    "data": { "changedFields": ["file_sign", "damage_type"] }
  • party.changed — party ist einer von INJURED_PARTY, DRIVER, OPPONENT_DRIVER, OPPONENT_OWNER, WITNESS; changedFields wie oben.

  • evaluation.values.changed — reason ist ADDED (erstmals erfasst) oder MODIFIED.

  • case.tag.changed — tag ist das Etikett, reason ADDED oder DELETED.

Kommentare​

comment.created und comment.updated tragen dieselben Felder — dieselben Werte, die GET /cases/{id}/comments liefert, nur ohne den Text:

"data": {
"commentId": "c0a8e1d2-3f4b-4c5d-8e6f-7a8b9c0d1e2f",
"createdBy": "m.mustermann",
"fullName": "Max Mustermann",
"creationDate": "2026-11-10T09:30:00.000+01:00",
"apiAuthored": false,
"customerAuthored": false,
"customerVisible": true
}

Kommentare aus dem Kundenportal tragen customerAuthored: true und den Namen "Kund_in (extern)". Den Text holst du über die API.

Dokumente​

  • attachmentId ist der Dublettenschlüssel für Dokumente — nicht der Dateiname. Es ist dieselbe Kennung, die GET /cases/{id}/attachments als attachmentId liefert; darüber findest du das Dokument bei dir wieder.

  • attachment.created: created ist der Anlagezeitpunkt (derselbe Wert wie AttachmentV1DTO.created), signable der Stand bei der Anlage. Wird ein Dokument später signiert, ändert sich signable in der API, nicht im bereits erzeugten Ereignis.

  • Wird dieselbe Datei überschrieben (etwa beim Signieren), entsteht kein neues attachment.created. Etikettwechsel kommen als attachment.tag.changed — auch der beim Signieren (POA → POA_SIGNED, reason MODIFIED). Ein Überschreiben ohne Etikettwechsel (etwa ein neu erzeugter Reparaturablaufplan) meldet nichts.

  • Wer hat signiert? An actor.channel: PORTAL heißt, die Kund_in hat über den Signaturprozess unterschrieben (actor.username ist dann "Kund_in (extern)"), sonst wurde in der App signiert oder über die API umetikettiert. Dieselbe Unterscheidung liefert die API über signingStatus (siehe Anhänge verwalten).

  • attachment.tag.changed: reason ist ADDED, MODIFIED oder DELETED.

    "data": {
    "attachmentId": "7f3c2a10-5b4e-4d6a-9c1e-2b8f0a4d6e91",
    "tag": "POA_SIGNED",
    "previousTag": "POA",
    "reason": "MODIFIED"
    }

ping: Testruf und Lebenszeichen​

Die Administrator:innen können jederzeit einen Testruf auslösen — derselbe Umschlag, dieselbe Anmeldung, derselbe Weg wie ein echtes Ereignis. Er hat keinen Fallbezug: kein caseId, kein case, keine sequence. data.sentAt ist der Zeitpunkt des Versands (gleich occurredAt), actor die Person, die den Testruf ausgelöst hat. Antworte darauf wie auf jedes andere Ereignis mit 2xx.

Lebenszeichen: Zusätzlich schickt die USP jedem aktiven Abo zur vollen Stunde einen ping — derselbe Umschlag, nur mit actor.channel SYSTEM und ohne username. Damit kannst du auf Stille alarmieren, auch wenn sich nachts oder am Wochenende kein Fall ändert. Angehaltene und gesperrte Abos bekommen bewusst keinen.

  • Antwortest du auf das Lebenszeichen mit 401 oder 403 — oder lehnt dein Token-Endpunkt ab —, wird das Abo gesperrt wie bei einer normalen Zustellung. So fällt ein abgelaufener oder entzogener Schlüssel auch ohne Fallverkehr auf.
  • Andere Fehler beim Lebenszeichen zählen nicht für den Schutzschalter; der nächste Ping kommt zur nächsten vollen Stunde.
  • Der Testruf aus der Verwaltung sperrt dagegen nie: dort sieht die Person das Ergebnis direkt.
{
"specVersion": "1",
"eventId": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
"eventType": "ping",
"occurredAt": "2026-11-10T15:00:00.123+01:00",
"subscriptionId": "3b9f0c6a1d2e4f5a8b7c6d5e4f3a2b1c",
"tenantRoot": "musterhaus",
"actor": { "channel": "APP", "username": "m.mustermann", "apiAuthored": false, "keyId": null },
"data": { "sentAt": "2026-11-10T15:00:00.123+01:00" }
}

Der Request​

POST /hooks/usp/v1 HTTP/1.1
Host: integrator.example.com
Content-Type: application/json
Authorization: Bearer …
X-USP-Event-Id: 6f1c2d9e-3b8a-4c57-9a0e-2d4b7c1e8f30
X-USP-Delivery-Id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d

{ …Umschlag… }
HeaderBedeutung
X-USP-Event-IdWie eventId im Umschlag — du kannst Dubletten erkennen, ohne den Rumpf zu lesen.
X-USP-Delivery-IdNeu bei jedem Versuch. Unterscheidet „nochmal geschickt" von „nochmal passiert".

Anmeldung​

Wie sich die USP bei dir ausweist, legt das Abo fest:

VerfahrenWas ankommt
Bearer-TokenAuthorization: Bearer <Schlüssel>
Eigener Header<Header-Name>: <Schlüssel>, z. B. X-Api-Key: …
OAuth2 Client CredentialsAuthorization: Bearer <Access-Token> — das Token holt die USP vorher an deinem Token-Endpunkt.

Bei OAuth2 Client Credentials (RFC 6749, Abschnitt 4.4) gibst du dem Betreiber Token-URL (nur https://, öffentlich erreichbar), Client-ID, Client-Secret und optional einen Scope. Die USP fragt dann so an:

POST /oauth2/token HTTP/1.1
Host: login.integrator.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=webhooks.write
  • Client-ID und -Secret gehen standardmäßig als Basic-Header mit (RFC 6749, 2.3.1 — Werte vor dem Base64 URL-kodiert). Auf Wunsch stattdessen im Formular-Rumpf (client_id, client_secret).
  • Deine Antwort braucht access_token; token_type muss fehlen oder Bearer sein. expires_in wird beachtet: die USP verwendet ein Token bis kurz vor Ablauf weiter. Fehlt die Angabe, rechnet sie mit 5 Minuten.
  • Antwortet die Ziel-URL mit 401, holt die USP einmal ein neues Token und wiederholt.
  • Lehnt dein Token-Endpunkt ab — jeder 4xx außer 408 und 429, oder eine Antwort ohne brauchbares Token —, wird das Abo gesperrt wie bei einem 401 der Ziel-URL. 5xx, 408, 429, Timeouts und Verbindungsfehler am Token-Endpunkt zählen als gewöhnlicher Fehlversuch.

Ein Client-Secret oder fester Schlüssel geht nur einmal an den Betreiber und wird verschlüsselt gespeichert; keine Antwort der USP enthält ihn wieder.

Zustellung​

Deine Antwort​

Antworte schnell: Die USP wartet höchstens 5 Sekunden auf den Verbindungsaufbau und 45 Sekunden auf die Antwort. Arbeite das Ereignis am besten asynchron ab und bestätige sofort.

AntwortFolge
2xxZugestellt.
429Die USP wartet so lange, wie Retry-After sagt (Sekunden oder HTTP-Datum; ohne Angabe 60 Sekunden) und versucht es dann erneut — ohne dass es als Fehlversuch zählt.
401, 403Das Abo wird sofort gesperrt. Nichts geht verloren: weitere Ereignisse sammeln sich eingefroren an und gehen nach dem erneuten Aktivieren in Reihenfolge raus. Antworte deshalb nie mit 401/403 auf ein vorübergehendes Problem.
400, 413, 415Die USP wertet das als ihren Fehler (falscher Umschlag): kein automatischer neuer Versuch. Der Betreiber kann das Ereignis nach einer Korrektur gezielt erneut senden.
3xx (Weiterleitungen verfolgt die USP nicht), andere 4xx, 5xx, Timeout, VerbindungsfehlerFehlversuch — die USP wiederholt später automatisch. Nach 5 Fehlversuchen in Folge sperrt ein Schutzschalter das Abo, damit ein längerer Ausfall nicht jedes wartende Ereignis einzeln verbrennt.

Rückmeldung im Antwortrumpf​

Über die Zustellung entscheidet allein der Statuscode. Schickst du bei 2xx zusätzlich JSON, liest die USP diese Felder und legt sie im Zustellprotokoll ab:

{
"correlationId": "c0ffee-1",
"runId": "run-7",
"decision": "STATUS_NO_MAPPING",
"classification": "no_effect_by_design"
}
FeldBedeutung
classificationVerbindlich. effect — die Zustellung hat gewirkt; no_effect_by_design — du hast bewusst nichts getan (etwa beim ping oder bei einem Status ohne Abbildung); no_effect_failure — sie hätte wirken sollen, hat aber nicht oder nicht vollständig.
decisionDein interner Katalogname — nur zur Anzeige.
correlationId, runIdDeine Kennungen, um den Vorgang bei dir wiederzufinden.

no_effect_failure wird bei der USP gezählt und als Fehler protokolliert, damit jemand den Fall mit dir klärt — aber nicht wiederholt: ein 2xx bleibt endgültig. Fehlt ein Feld oder hat es einen unbekannten Wert, wird die Zustellung trotzdem normal protokolliert.

Wiederholung​

Ein Fehlversuch (letzte Tabellenzeile) wird automatisch wiederholt — insgesamt bis zu 9 Versuche. Der Abstand beginnt bei 5 Minuten und verdoppelt sich bis höchstens 6 Stunden, jeweils ±20 % gestreut; zwischen erstem und letztem Versuch liegen so rund 16½ Stunden. Danach gibt die USP das Ereignis auf, und der Betreiber kann es gezielt erneut senden. Jeder Versuch trägt dieselbe eventId und eine neue X-USP-Delivery-Id.

429 zählt nicht als Versuch, sondern wird nach Retry-After wiederholt.

Dubletten​

Rechne damit, dass ein Ereignis mehr als einmal ankommt — vor allem durch die automatische Wiederholung: Läuft deine Antwort in den Timeout, obwohl du schon verarbeitet hattest, kommt dasselbe Ereignis noch einmal. Ebenso, wenn der Betreiber einen Bereich erneut sendet. Prüfe deshalb jede eventId gegen die schon verarbeiteten und bestätige eine bekannte mit 2xx, ohne sie noch einmal auszuführen.

Reihenfolge​

Je Fall und Abo ist höchstens eine Zustellung gleichzeitig unterwegs. Wartet ein Ereignis eines Falls (etwa nach 429), warten die späteren desselben Falls mit. Ereignisse verschiedener Fälle können sich überholen.

Verlass dich trotzdem auf sequence: sie steigt je Fall streng an. Ist die sequence eines Ereignisses kleiner als die zuletzt verarbeitete desselben Falls, ist es veraltet — lies den Fall dann lieber nach, als den alten Stand anzuwenden. Lücken in der Nummerierung sind normal.

Zusammenfassen​

Nur case.changed wird zusammengefasst: Gehen innerhalb von 10 Sekunden mehrere davon für denselben Fall ein, kommt ein Ereignis mit der Vereinigung aller changedFields an. Das kostet bis zu 10 Sekunden Verzögerung. Ereignisse mit eigener Identität — Kommentare, Dokumente, Statuswechsel — werden nie zusammengefasst.

Takt​

Die USP stellt je Abo standardmäßig höchstens 12 Ereignisse pro Minute zu, gleichmäßig verteilt statt gebündelt. Der Betreiber kann den Wert je Abo anpassen. So bleibt dir Spielraum, zu jedem Ereignis Details über die API nachzulesen, ohne in deren Ratenbegrenzung zu laufen.

Was gefiltert wird​

Ein Abo stellt nur zu, was zu ihm passt. Das Zurückhalten ist kein Fehler und wird mit Grund protokolliert:

  • Ereignisart nicht abonniert.
  • Fall außerhalb des Mandanten oder des Standortfilters des Abos. Maßgeblich ist der Stand beim Ereignis: Wechselt ein Fall danach den Standort, verschwindet ein bereits erzeugtes Ereignis nicht mehr aus dem Abo.
  • Schleifenschutz: Auf Wunsch hält das Abo Ereignisse zurück, die dein eigener API-Schlüssel ausgelöst hat (je Ereignisart nach keyId oder channel). Ohne diese Regel bekommst du auch deine eigenen Änderungen gemeldet — und erkennst sie an actor.keyId.

Empfohlenes Vorgehen​

  1. Prüfe die Anmeldung (Bearer, Header oder dein eigener OAuth2-Token).
  2. Bestätige sofort mit 2xx und verarbeite danach.
  3. Verwirf Dubletten über eventId, Dokumente zusätzlich über attachmentId.
  4. Lies nach, was du brauchst, über die API v1 — der Webhook ist der Auslöser, die API die Wahrheit.
  5. Behalte den Abgleich über changedSince bei, nur seltener (z. B. stündlich). Er ist dein Netz, falls ein Ereignis während einer Störung auf deiner Seite verloren geht.