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
}
}
| Feld | Bedeutung |
|---|---|
specVersion | Version des Umschlags. Heute "1". |
eventId | Kennung des Ereignisses. Dein Dublettenschlüssel — eine erneute Zustellung desselben Ereignisses trägt dieselbe eventId. |
eventType | Ereignisart, siehe Ereignisse. |
occurredAt | Wann die Änderung passiert ist. |
sequence | Fortlaufende Nummer, je Fall streng steigend, mit Lücken (die Nummer ist über alle Fälle vergeben). Daran stellst du die Reihenfolge wieder her. |
subscriptionId | Kennung des Abos, über das die Zustellung läuft. |
tenantRoot | Mandant des Abos. |
caseId | Der betroffene Fall. |
actor | Wer die Änderung ausgelöst hat, siehe unten. |
case | Der Fallrahmen, siehe unten. |
data | Ereignisspezifische 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
nullzu sein. Die einzige Ausnahme istactor.keyId. - Unbekannte Felder ignorierst du — der Umschlag darf wachsen. Ebenso unbekannte Werte in
status,channelodertag. - Kein Freitext. Weder Kommentartext noch Unfallhergang noch Stornobegründung verlassen die
USP über einen Webhook.
dataenthält Feldnamen, Kennungen und Aufzählungswerte.
actor
| Feld | Bedeutung |
|---|---|
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. |
username | Wer gehandelt hat. Über die API ist das der technische Benutzer deines Mandanten. |
apiAuthored | true, 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
eventType | Wann | data |
|---|---|---|
case.status.changed | Der Status eines Falls wechselt. | status, previousStatus; bei CANCELLED zusätzlich hasCancellationReason |
case.changed | Fallfelder werden geändert — auch beim Anlegen eines Falls. | changedFields |
party.changed | Angaben zu einer beteiligten Person werden geändert. | party, changedFields |
evaluation.values.changed | Regulierungswerte werden erfasst oder geändert. | reason, changedFields |
case.tag.changed | Ein Fall-Etikett wird gesetzt oder entfernt. | tag, reason |
comment.created | Ein Kommentar wird geschrieben. | siehe Kommentare |
comment.updated | Ein Kommentar wird bearbeitet. | siehe Kommentare |
attachment.created | Ein Dokument wird hochgeladen oder erzeugt. | attachmentId, fileName, created, tag, signable |
attachment.deleted | Ein Dokument wird gelöscht. | attachmentId, fileName, tag |
attachment.tag.changed | Das Etikett eines Dokuments wird gesetzt, geändert oder entfernt. | attachmentId, tag, previousTag, reason |
case.locations.changed | Abonnierbar, wird derzeit noch nicht erzeugt. | — |
ping | Testruf aus der Verwaltung und stündlich als Lebenszeichen. | sentAt |
Fall und Beteiligte
-
case.status.changed—statusist der Status, in den der Fall mit diesem Ereignis gewechselt ist,previousStatusder vorherige (fehlt, wenn es keinen gab). Nimm den Status ausdata, nicht aus dem Fallrahmen: wechselt ein Fall zweimal kurz hintereinander, zeigtcase.statusin beiden Ereignissen schon den jüngsten Stand. Ein Speichern ohne Statuswechsel erzeugt kein Ereignis. Bei einer Stornierung sagthasCancellationReasonnur, ob eine Begründung vorliegt — den Text liest du über die API."data": { "status": "CANCELLED", "previousStatus": "RELEASED", "hasCancellationReason": true } -
case.changed—changedFieldsnennt die geänderten Felder insnake_case, ohne Werte. Mehrere Änderungen am selben Fall innerhalb von 10 Sekunden werden zu einem Ereignis zusammengefasst;changedFieldsist dann die Vereinigung (siehe Zusammenfassen)."data": { "changedFields": ["file_sign", "damage_type"] } -
party.changed—partyist einer vonINJURED_PARTY,DRIVER,OPPONENT_DRIVER,OPPONENT_OWNER,WITNESS;changedFieldswie oben. -
evaluation.values.changed—reasonistADDED(erstmals erfasst) oderMODIFIED. -
case.tag.changed—tagist das Etikett,reasonADDEDoderDELETED.
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
-
attachmentIdist der Dublettenschlüssel für Dokumente — nicht der Dateiname. Es ist dieselbe Kennung, dieGET /cases/{id}/attachmentsalsattachmentIdliefert; darüber findest du das Dokument bei dir wieder. -
attachment.created:createdist der Anlagezeitpunkt (derselbe Wert wieAttachmentV1DTO.created),signableder Stand bei der Anlage. Wird ein Dokument später signiert, ändert sichsignablein der API, nicht im bereits erzeugten Ereignis. -
Wird dieselbe Datei überschrieben (etwa beim Signieren), entsteht kein neues
attachment.created. Etikettwechsel kommen alsattachment.tag.changed— auch der beim Signieren (POA→POA_SIGNED,reasonMODIFIED). Ein Überschreiben ohne Etikettwechsel (etwa ein neu erzeugter Reparaturablaufplan) meldet nichts. -
Wer hat signiert? An
actor.channel:PORTALheißt, die Kund_in hat über den Signaturprozess unterschrieben (actor.usernameist dann"Kund_in (extern)"), sonst wurde in der App signiert oder über die API umetikettiert. Dieselbe Unterscheidung liefert die API übersigningStatus(siehe Anhänge verwalten). -
attachment.tag.changed:reasonistADDED,MODIFIEDoderDELETED."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
401oder403— 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… }
| Header | Bedeutung |
|---|---|
X-USP-Event-Id | Wie eventId im Umschlag — du kannst Dubletten erkennen, ohne den Rumpf zu lesen. |
X-USP-Delivery-Id | Neu bei jedem Versuch. Unterscheidet „nochmal geschickt" von „nochmal passiert". |
Anmeldung
Wie sich die USP bei dir ausweist, legt das Abo fest:
| Verfahren | Was ankommt |
|---|---|
| Bearer-Token | Authorization: Bearer <Schlüssel> |
| Eigener Header | <Header-Name>: <Schlüssel>, z. B. X-Api-Key: … |
| OAuth2 Client Credentials | Authorization: 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_typemuss fehlen oderBearersein.expires_inwird 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
4xxaußer408und429, oder eine Antwort ohne brauchbares Token —, wird das Abo gesperrt wie bei einem401der 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.
| Antwort | Folge |
|---|---|
2xx | Zugestellt. |
429 | Die 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, 403 | Das 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, 415 | Die 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, Verbindungsfehler | Fehlversuch — 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"
}
| Feld | Bedeutung |
|---|---|
classification | Verbindlich. 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. |
decision | Dein interner Katalogname — nur zur Anzeige. |
correlationId, runId | Deine 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
keyIdoderchannel). Ohne diese Regel bekommst du auch deine eigenen Änderungen gemeldet — und erkennst sie anactor.keyId.
Empfohlenes Vorgehen
- Prüfe die Anmeldung (Bearer, Header oder dein eigener OAuth2-Token).
- Bestätige sofort mit
2xxund verarbeite danach. - Verwirf Dubletten über
eventId, Dokumente zusätzlich überattachmentId. - Lies nach, was du brauchst, über die API v1 — der Webhook ist der Auslöser, die API die Wahrheit.
- Behalte den Abgleich über
changedSincebei, nur seltener (z. B. stündlich). Er ist dein Netz, falls ein Ereignis während einer Störung auf deiner Seite verloren geht.