Zum Inhalt springen

Referenz: Webhooks

Alle Ereignisse des Vertrags Webhooks 3.1.0, erzeugt aus der OpenAPI-Datei /spec/webhooks.yaml.

Zum Lesen: Der einzige Pfad darin, /subscribe-via-self-service, ist keine aufrufbare Adresse. OpenAPI 3.0 kann Callbacks nur unterhalb einer Operation beschreiben — dieser Eintrag ist der Aufhänger dafür und wird von keinem Server bedient. Angelegt werden Webhooks im Dashboard; die Callbacks beschreiben, was Ihr eigener Endpunkt empfängt. Wie Sie ihn bauen, steht unter Webhooks.

POWRdrive Webhooks · 3.1.0

OpenAPI-YAML

Alle Endpunkte und Datentypen zum Aufklappen. Aus der YAML lässt sich zusätzlich Client-/Server-Code generieren.

Endpunkte

POST/subscribe-via-self-serviceKein aufrufbarer Endpunkt — Platzhalter für die Callback-Modellierung

**Diese Adresse gibt es nicht.** OpenAPI 3.0 kann Callbacks nur unterhalb einer Operation beschreiben; dieser Eintrag ist der Aufhänger dafür und wird von keinem Server bedient. Ein Aufruf geht ins Leere. Webhooks werden im Self-Service-Bereich unter „Webhooks" angelegt — dort entstehen auch `webhookId` und `signatureSecret`. Die Callbacks weiter unten beschreiben, was Ihr eigener Endpunkt empfängt.

Parameter

webhookUrl*query

Antworten

201 Webhook angelegt
webhookId* WebhookId
signatureSecret* WebhookSignatureSecret

Datentypen

TYPWebhookId

—

TYPWebhookSignatureSecret

—

TYPWebhookEventType

Werte: PING, VEHICLE_DEREGISTRATION_XKFZ_EVENT, VEHICLE_HOLDER_CHANGE_XKFZ_EVENT, VEHICLE_TRANSFER_XKFZ_EVENT, VEHICLE_REREGISTRATION_XKFZ_EVENT, VEHICLE_REGISTRATION_XKFZ_EVENT, FEE_NOTICE_XKFZ_EVENT, UNMATCHED_MESSAGE_XKFZ_EVENT, DELIVERY_SHIPMENT, DELIVERY_RETURN, DELIVERY_CANCELLATION, LICENSE_PLATE_RESERVATION_APPROVAL, LICENSE_PLATE_RESERVATION_REJECTION, LICENSE_PLATE_RESERVATION_TIMEOUT

TYPLocalDateTime
"2026-07-20T09:15:30"
TYPWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
TYPWebhookEventOrder
id* integer (int64)
externalId string
Ihre eigene Referenz aus dem auslösenden Auftrag; null, wenn keine angegeben war.
TYPWebhookLicensePlateComponents
usageType string
city string
middle string
end string
TYPWebhookReservationCustomization
registrationOfficeServiceId integer
licensePlateNumberComponents WebhookLicensePlateComponents
usageType string
city string
middle string
end string
licensePlateType string
vehicleType string
seasonStartMonth integer
seasonEndMonth integer
TYPPingWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "PING",
  "eventTime": "2026-07-20T09:15:30"
}
TYPVehicleDeregistrationXkfzEventWebhookEventStatus

Werte: ACCEPTED, APPROVED, APPROVED_WITH_DOCUMENTS, FAILED, FORWARDED, PROCESSED, REJECTED, REJECTED_WITH_DOCUMENTS, UNKNOWN

TYPVehicleDeregistrationXkfzEventWebhookEventFilePurposeType

Werte: CERTIFICATE, RECEIPT, APPLICATION, UNSPECIFIED

TYPVehicleDeregistrationXkfzEventWebhookEventFile
purposeType* VehicleDeregistrationXkfzEventWebhookEventFilePurposeType
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}. Der Schlüssel eines Vorgangsbelegs gilt 72 Stunden ab dem Ablegen (`expirationTime`); danach ergibt der Abruf 404, und der Beleg ist im Dashboard erneut freizugeben.
expirationTime* object
**Anderes Format als in der Auskunft — beides ist so gewollt.** Hier steht wie bei jedem Zeitstempel eines Ereignisses ein `LocalDateTime`: ISO 8601 in UTC, OHNE Zonenangabe und sekundengenau (`2026-09-19T14:38:22`). Dieselbe Frist liefert `GET …/orders/{orderId}` als vollständigen ISO-Zeitstempel MIT Zone und Millisekunden (`2026-09-19T14:38:22.558Z`). Der Zeitpunkt ist derselbe; wer beide Quellen vergleicht, muss den Wert des Ereignisses als UTC lesen. Das Format des Ereignisses folgt dem Vorbild kennzeichen.dev und bleibt deshalb, wie es ist.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden. Derselbe Wert wie in der Vorgangsauskunft.
TYPVehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
TYPVehicleDeregistrationXkfzEventWebhookEventCostBreakdown
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
TYPVehicleDeregistrationXkfzEventWebhookEventMessage
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
TYPVehicleDeregistrationXkfzEventWebhookEventParty
role* string
Codeliste `rolle`; `2` ist der Halter.
roleName string
Klartext der Rolle aus der Codeliste `rolle`, etwa `Halter`. Fehlt, wenn die Nachricht keinen führt.
kind* enum
natürliche Person, juristische Person, Vereinigung.
natural · legal · association
name* string
representative string
Nur bei einer Vereinigung (z. B. GbR) und nur, wenn die Nachricht einen führt — der benannte Vertreter, eine natürliche oder juristische Person. Seit XKfz 6.0 optional; fehlt er, fehlt das Feld.
TYPXkfzEventPayload
attemptOf integer
Der **Auftrag**, zu dem dieses Ereignis gehört — beim ersten Versuch die eigene Id. **Ordnen Sie hierüber zu, nicht über `order.id`.** Wird ein abgewiesener Antrag korrigiert, entsteht beim KBA ein zweiter Antrag; das Ereignis dazu trägt dessen Id. Diese Id kommt in `GET …/orders` **nicht** vor — die Liste führt nur Auftragsköpfe. Wer Ereignisse über `order.id` zuordnet, legt damit einen Auftrag an, den er über die Liste nie wiederfindet. Das ist kein Randfall: Es passiert auch dem, der die volle Zustellhistorie vor sich hat und Ereignisse ausdrücklich zuordnen will.
attempt integer
Laufende Nummer des Versuchs. `1` beim ersten Antrag, `2` nach der ersten Korrektur.
order* object
id* integer (int64)
externalId string
businessTransaction enum
Der Geschäftsvorfall des Vorgangs — derselbe Wert wie `businessTransaction` in der Vorgangsauskunft. NZ und TZ teilen sich den Ereignistyp, WG und WZ ebenso; an diesem Feld erkennen Sie, welcher Vorfall beschieden wurde — auch bei Anträgen, die nicht über Ihre Schnittstelle, sondern über das Dashboard (Formular, Stapel, Korrektur) gestellt wurden.
AB · HA · UG · WG · WZ · NZ · TZ
status* VehicleDeregistrationXkfzEventWebhookEventStatus
derivedStatus* enum
Fachliche Einordnung im Vokabular von kennzeichen.dev. PENDING/SUCCESS/FAILURE sind Schwebe, Erfolg und nicht einordenbare Ablehnung; die uebrigen Werte benennen die Ablehnungsart, aus der ein Empfaenger Kundenaktion und Korrekturmaske ableitet. RESERVATION_IMPOSSIBLE — eine Kennzeichenreservierung ist nach Kennzeichenmitnahme nicht moeglich (Quittung 00764 mit entsprechendem Zusatz); ohne Reservierung neu einreichen. ERROR_UNHANDLED — NUR bei der Ausserbetriebsetzung (AB): Die Schemapruefung des KBA hat den Antrag an Registerdaten abgewiesen (00300 Namensbestandteile, 00301 Halter fehlt); dort senden wir keinen Halter, und weder Kundenkorrektur noch erneutes Einreichen helfen, der Fall gehoert in die manuelle Pruefung. Bei allen anderen Vorfaellen (HA, UG, WG, WZ, NZ, TZ) kommt eine Schemapruefung als FAILURE — sie ist dort ein Eingabefehler, der Grund steht in `messages[].additional` (Praefix `SCHEMAPRUEFUNG`), und der Antrag ist zu korrigieren. Beide Werte sendet dieses System seit dem 07.09.2026; sie standen bis zum 12.09.2026 nicht in diesem Vertrag. INPUT_INVALID — derzeit nicht gesendet; aus Kompatibilitätsgründen im Wertebereich. Eine Ablehnung, die die Zulassungsbehoerde im Bescheid (0709) begruendet — etwa Steuer- oder Gebuehrenrueckstaende —, hat kein eigenes Wort und kommt als FAILURE; die Gruende stehen in `messages` (Code und Klartext der Codeliste `ablehnungsgrund`).
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
files VehicleDeregistrationXkfzEventWebhookEventFile[]
purposeType* VehicleDeregistrationXkfzEventWebhookEventFilePurposeType
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}. Der Schlüssel eines Vorgangsbelegs gilt 72 Stunden ab dem Ablegen (`expirationTime`); danach ergibt der Abruf 404, und der Beleg ist im Dashboard erneut freizugeben.
expirationTime* object
**Anderes Format als in der Auskunft — beides ist so gewollt.** Hier steht wie bei jedem Zeitstempel eines Ereignisses ein `LocalDateTime`: ISO 8601 in UTC, OHNE Zonenangabe und sekundengenau (`2026-09-19T14:38:22`). Dieselbe Frist liefert `GET …/orders/{orderId}` als vollständigen ISO-Zeitstempel MIT Zone und Millisekunden (`2026-09-19T14:38:22.558Z`). Der Zeitpunkt ist derselbe; wer beide Quellen vergleicht, muss den Wert des Ereignisses als UTC lesen. Das Format des Ereignisses folgt dem Vorbild kennzeichen.dev und bleibt deshalb, wie es ist.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden. Derselbe Wert wie in der Vorgangsauskunft.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709). **Nur bei eigener KBA-Registrierung** (Selbstabrechner): Ein Vertragspartner unter unserer Registrierung bekommt die amtlichen Beträge nicht zugestellt — er sieht sie auch in Auskunft und Dashboard nicht und bezahlt unsere Rechnung. Derselbe Wert steht als `costBreakdown` in der Vorgangsauskunft (`GET …/orders/{orderId}`), für den Abgleich nach einem verlorenen Ereignis.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
messages VehicleDeregistrationXkfzEventWebhookEventMessage[]
Die Meldungen des KBA (Quittungscode, Klartext, Zusatz). Nicht verpflichtend: Gibt es keine — der Regelfall beim Erfolg —, FEHLT das Feld im Ereignis. Die Vorgangsauskunft (`GET …/orders/{orderId}`) fuehrt an derselben Stelle ein leeres Array. Wer beide Quellen liest, behandelt „fehlt", `null` und `[]` gleich.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
applicationId string
Antragsnummer des KBA, 20-stellig.
licensePlate string
Das Kennzeichen des Vorgangs in Anzeigeform (`KBA-NZ 123`) — derselbe Wert wie `licensePlate` in der Vorgangsauskunft. Bei Vorfällen, die ein Kennzeichen zuteilen (NZ, TZ, UG, WG, WZ), steht hier nach dem Bescheid das zugeteilte. `registrationData.Kennzeichen` führt es dagegen in der Drahtform des KBA (`KBANZ 123`) und nur, wenn die Zulassungsdaten angefordert wurden. Fehlt, solange der Vorgang keines trägt.
retryable boolean
Gesetzt, wenn der Vorgang nur **vorübergehend** gescheitert ist — etwa weil das i-Kfz-Portal ausgefallen war oder der Zuständigkeitsfinder nicht antwortete. Derselbe Antrag hat später Aussicht auf Erfolg. Nur ein Hinweis, keine Zusage: Ob der Antrag beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Wer selbsttätig erneut sendet, riskiert die Doppelzulassung.
registrationData object
Die strukturierten Zulassungsdaten, sofern der Antrag sie über `requestRegistrationData` angefordert hat und das KBA sie geliefert hat — über sechzig Angaben aus den Zulassungsbescheinigungen (Kennzeichen, Erstzulassung, Fahrzeugklasse, Hubraum, CO2-Werte, Massen, Achslasten, Bereifung, Termin der nächsten Hauptuntersuchung). Die Feldnamen sind die des XKfz-Standards.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev — der Vertrag des Vorbilds kennt das Feld nicht. Es kommt zusätzlich und ist optional; ein bestehender Empfänger merkt davon nichts. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen — Zulassungsbescheinigung Teil I und Teil II, Stempelplaketten, Feinstaubplakette — wie gewünscht versandt wurden oder zur Abholung bereitliegen. Derselbe Wert steht in der Vorgangsauskunft (`GET …/orders/{orderId}`). Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung; eine Außerbetriebsetzung führt die Angabe nicht. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Sie entscheidet auch nichts: Ob der Antrag durch ist, sagen `status` und `derivedStatus`.
parties VehicleDeregistrationXkfzEventWebhookEventParty[]
Die Beteiligten aus dem Rückkanal — vor allem der Halter.
role* string
Codeliste `rolle`; `2` ist der Halter.
roleName string
Klartext der Rolle aus der Codeliste `rolle`, etwa `Halter`. Fehlt, wenn die Nachricht keinen führt.
kind* enum
natürliche Person, juristische Person, Vereinigung.
natural · legal · association
name* string
representative string
Nur bei einer Vereinigung (z. B. GbR) und nur, wenn die Nachricht einen führt — der benannte Vertreter, eine natürliche oder juristische Person. Seit XKfz 6.0 optional; fehlt er, fehlt das Feld.
TYPVehicleDeregistrationXkfzEventWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
attemptOf integer
Der **Auftrag**, zu dem dieses Ereignis gehört — beim ersten Versuch die eigene Id. **Ordnen Sie hierüber zu, nicht über `order.id`.** Wird ein abgewiesener Antrag korrigiert, entsteht beim KBA ein zweiter Antrag; das Ereignis dazu trägt dessen Id. Diese Id kommt in `GET …/orders` **nicht** vor — die Liste führt nur Auftragsköpfe. Wer Ereignisse über `order.id` zuordnet, legt damit einen Auftrag an, den er über die Liste nie wiederfindet. Das ist kein Randfall: Es passiert auch dem, der die volle Zustellhistorie vor sich hat und Ereignisse ausdrücklich zuordnen will.
attempt integer
Laufende Nummer des Versuchs. `1` beim ersten Antrag, `2` nach der ersten Korrektur.
order* object
id* integer (int64)
externalId string
businessTransaction enum
Der Geschäftsvorfall des Vorgangs — derselbe Wert wie `businessTransaction` in der Vorgangsauskunft. NZ und TZ teilen sich den Ereignistyp, WG und WZ ebenso; an diesem Feld erkennen Sie, welcher Vorfall beschieden wurde — auch bei Anträgen, die nicht über Ihre Schnittstelle, sondern über das Dashboard (Formular, Stapel, Korrektur) gestellt wurden.
AB · HA · UG · WG · WZ · NZ · TZ
status* VehicleDeregistrationXkfzEventWebhookEventStatus
derivedStatus* enum
Fachliche Einordnung im Vokabular von kennzeichen.dev. PENDING/SUCCESS/FAILURE sind Schwebe, Erfolg und nicht einordenbare Ablehnung; die uebrigen Werte benennen die Ablehnungsart, aus der ein Empfaenger Kundenaktion und Korrekturmaske ableitet. RESERVATION_IMPOSSIBLE — eine Kennzeichenreservierung ist nach Kennzeichenmitnahme nicht moeglich (Quittung 00764 mit entsprechendem Zusatz); ohne Reservierung neu einreichen. ERROR_UNHANDLED — NUR bei der Ausserbetriebsetzung (AB): Die Schemapruefung des KBA hat den Antrag an Registerdaten abgewiesen (00300 Namensbestandteile, 00301 Halter fehlt); dort senden wir keinen Halter, und weder Kundenkorrektur noch erneutes Einreichen helfen, der Fall gehoert in die manuelle Pruefung. Bei allen anderen Vorfaellen (HA, UG, WG, WZ, NZ, TZ) kommt eine Schemapruefung als FAILURE — sie ist dort ein Eingabefehler, der Grund steht in `messages[].additional` (Praefix `SCHEMAPRUEFUNG`), und der Antrag ist zu korrigieren. Beide Werte sendet dieses System seit dem 07.09.2026; sie standen bis zum 12.09.2026 nicht in diesem Vertrag. INPUT_INVALID — derzeit nicht gesendet; aus Kompatibilitätsgründen im Wertebereich. Eine Ablehnung, die die Zulassungsbehoerde im Bescheid (0709) begruendet — etwa Steuer- oder Gebuehrenrueckstaende —, hat kein eigenes Wort und kommt als FAILURE; die Gruende stehen in `messages` (Code und Klartext der Codeliste `ablehnungsgrund`).
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
files VehicleDeregistrationXkfzEventWebhookEventFile[]
purposeType* VehicleDeregistrationXkfzEventWebhookEventFilePurposeType
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}. Der Schlüssel eines Vorgangsbelegs gilt 72 Stunden ab dem Ablegen (`expirationTime`); danach ergibt der Abruf 404, und der Beleg ist im Dashboard erneut freizugeben.
expirationTime* object
**Anderes Format als in der Auskunft — beides ist so gewollt.** Hier steht wie bei jedem Zeitstempel eines Ereignisses ein `LocalDateTime`: ISO 8601 in UTC, OHNE Zonenangabe und sekundengenau (`2026-09-19T14:38:22`). Dieselbe Frist liefert `GET …/orders/{orderId}` als vollständigen ISO-Zeitstempel MIT Zone und Millisekunden (`2026-09-19T14:38:22.558Z`). Der Zeitpunkt ist derselbe; wer beide Quellen vergleicht, muss den Wert des Ereignisses als UTC lesen. Das Format des Ereignisses folgt dem Vorbild kennzeichen.dev und bleibt deshalb, wie es ist.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden. Derselbe Wert wie in der Vorgangsauskunft.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709). **Nur bei eigener KBA-Registrierung** (Selbstabrechner): Ein Vertragspartner unter unserer Registrierung bekommt die amtlichen Beträge nicht zugestellt — er sieht sie auch in Auskunft und Dashboard nicht und bezahlt unsere Rechnung. Derselbe Wert steht als `costBreakdown` in der Vorgangsauskunft (`GET …/orders/{orderId}`), für den Abgleich nach einem verlorenen Ereignis.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
messages VehicleDeregistrationXkfzEventWebhookEventMessage[]
Die Meldungen des KBA (Quittungscode, Klartext, Zusatz). Nicht verpflichtend: Gibt es keine — der Regelfall beim Erfolg —, FEHLT das Feld im Ereignis. Die Vorgangsauskunft (`GET …/orders/{orderId}`) fuehrt an derselben Stelle ein leeres Array. Wer beide Quellen liest, behandelt „fehlt", `null` und `[]` gleich.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
applicationId string
Antragsnummer des KBA, 20-stellig.
licensePlate string
Das Kennzeichen des Vorgangs in Anzeigeform (`KBA-NZ 123`) — derselbe Wert wie `licensePlate` in der Vorgangsauskunft. Bei Vorfällen, die ein Kennzeichen zuteilen (NZ, TZ, UG, WG, WZ), steht hier nach dem Bescheid das zugeteilte. `registrationData.Kennzeichen` führt es dagegen in der Drahtform des KBA (`KBANZ 123`) und nur, wenn die Zulassungsdaten angefordert wurden. Fehlt, solange der Vorgang keines trägt.
retryable boolean
Gesetzt, wenn der Vorgang nur **vorübergehend** gescheitert ist — etwa weil das i-Kfz-Portal ausgefallen war oder der Zuständigkeitsfinder nicht antwortete. Derselbe Antrag hat später Aussicht auf Erfolg. Nur ein Hinweis, keine Zusage: Ob der Antrag beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Wer selbsttätig erneut sendet, riskiert die Doppelzulassung.
registrationData object
Die strukturierten Zulassungsdaten, sofern der Antrag sie über `requestRegistrationData` angefordert hat und das KBA sie geliefert hat — über sechzig Angaben aus den Zulassungsbescheinigungen (Kennzeichen, Erstzulassung, Fahrzeugklasse, Hubraum, CO2-Werte, Massen, Achslasten, Bereifung, Termin der nächsten Hauptuntersuchung). Die Feldnamen sind die des XKfz-Standards.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev — der Vertrag des Vorbilds kennt das Feld nicht. Es kommt zusätzlich und ist optional; ein bestehender Empfänger merkt davon nichts. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen — Zulassungsbescheinigung Teil I und Teil II, Stempelplaketten, Feinstaubplakette — wie gewünscht versandt wurden oder zur Abholung bereitliegen. Derselbe Wert steht in der Vorgangsauskunft (`GET …/orders/{orderId}`). Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung; eine Außerbetriebsetzung führt die Angabe nicht. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Sie entscheidet auch nichts: Ob der Antrag durch ist, sagen `status` und `derivedStatus`.
parties VehicleDeregistrationXkfzEventWebhookEventParty[]
Die Beteiligten aus dem Rückkanal — vor allem der Halter.
role* string
Codeliste `rolle`; `2` ist der Halter.
roleName string
Klartext der Rolle aus der Codeliste `rolle`, etwa `Halter`. Fehlt, wenn die Nachricht keinen führt.
kind* enum
natürliche Person, juristische Person, Vereinigung.
natural · legal · association
name* string
representative string
Nur bei einer Vereinigung (z. B. GbR) und nur, wenn die Nachricht einen führt — der benannte Vertreter, eine natürliche oder juristische Person. Seit XKfz 6.0 optional; fehlt er, fehlt das Feld.
{
  "eventType": "VEHICLE_DEREGISTRATION_XKFZ_EVENT",
  "order": {
    "id": 1000,
    "externalId": "bestellung-4711"
  },
  "status": "APPROVED_WITH_DOCUMENTS",
  "derivedStatus": "SUCCESS",
  "applicationId": "88888020240510000003",
  "files": [
    {
      "purposeType": "CERTIFICATE",
      "mediaType": "application/pdf",
      "fileAccessKey": "1000_11111111-1111-1111-1111-111111111111_0",
      "expirationTime": "2026-07-23T09:15:30"
    }
  ],
  "costBreakdown": {
    "kbaCost": 30,
    "registrationOfficeCosts": {
      "items": [
        {
          "number": 1,
          "code": "224.2",
          "name": "GebOSt Gebührennummer 224.2",
          "amount": 210,
          "note": "Außerbetriebsetzung internetbasiert"
        },
        {
          "number": 2,
          "code": "125",
          "amount": 60
        }
      ],
      "total": {
        "number": 3,
        "name": "Summe",
        "amount": 270
      }
    }
  },
  "eventTime": "2026-07-20T09:15:30"
}
TYPVehicleHolderChangeXkfzEventWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
attemptOf integer
Der **Auftrag**, zu dem dieses Ereignis gehört — beim ersten Versuch die eigene Id. **Ordnen Sie hierüber zu, nicht über `order.id`.** Wird ein abgewiesener Antrag korrigiert, entsteht beim KBA ein zweiter Antrag; das Ereignis dazu trägt dessen Id. Diese Id kommt in `GET …/orders` **nicht** vor — die Liste führt nur Auftragsköpfe. Wer Ereignisse über `order.id` zuordnet, legt damit einen Auftrag an, den er über die Liste nie wiederfindet. Das ist kein Randfall: Es passiert auch dem, der die volle Zustellhistorie vor sich hat und Ereignisse ausdrücklich zuordnen will.
attempt integer
Laufende Nummer des Versuchs. `1` beim ersten Antrag, `2` nach der ersten Korrektur.
order* object
id* integer (int64)
externalId string
businessTransaction enum
Der Geschäftsvorfall des Vorgangs — derselbe Wert wie `businessTransaction` in der Vorgangsauskunft. NZ und TZ teilen sich den Ereignistyp, WG und WZ ebenso; an diesem Feld erkennen Sie, welcher Vorfall beschieden wurde — auch bei Anträgen, die nicht über Ihre Schnittstelle, sondern über das Dashboard (Formular, Stapel, Korrektur) gestellt wurden.
AB · HA · UG · WG · WZ · NZ · TZ
status* VehicleDeregistrationXkfzEventWebhookEventStatus
derivedStatus* enum
Fachliche Einordnung im Vokabular von kennzeichen.dev. PENDING/SUCCESS/FAILURE sind Schwebe, Erfolg und nicht einordenbare Ablehnung; die uebrigen Werte benennen die Ablehnungsart, aus der ein Empfaenger Kundenaktion und Korrekturmaske ableitet. RESERVATION_IMPOSSIBLE — eine Kennzeichenreservierung ist nach Kennzeichenmitnahme nicht moeglich (Quittung 00764 mit entsprechendem Zusatz); ohne Reservierung neu einreichen. ERROR_UNHANDLED — NUR bei der Ausserbetriebsetzung (AB): Die Schemapruefung des KBA hat den Antrag an Registerdaten abgewiesen (00300 Namensbestandteile, 00301 Halter fehlt); dort senden wir keinen Halter, und weder Kundenkorrektur noch erneutes Einreichen helfen, der Fall gehoert in die manuelle Pruefung. Bei allen anderen Vorfaellen (HA, UG, WG, WZ, NZ, TZ) kommt eine Schemapruefung als FAILURE — sie ist dort ein Eingabefehler, der Grund steht in `messages[].additional` (Praefix `SCHEMAPRUEFUNG`), und der Antrag ist zu korrigieren. Beide Werte sendet dieses System seit dem 07.09.2026; sie standen bis zum 12.09.2026 nicht in diesem Vertrag. INPUT_INVALID — derzeit nicht gesendet; aus Kompatibilitätsgründen im Wertebereich. Eine Ablehnung, die die Zulassungsbehoerde im Bescheid (0709) begruendet — etwa Steuer- oder Gebuehrenrueckstaende —, hat kein eigenes Wort und kommt als FAILURE; die Gruende stehen in `messages` (Code und Klartext der Codeliste `ablehnungsgrund`).
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
files VehicleDeregistrationXkfzEventWebhookEventFile[]
purposeType* VehicleDeregistrationXkfzEventWebhookEventFilePurposeType
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}. Der Schlüssel eines Vorgangsbelegs gilt 72 Stunden ab dem Ablegen (`expirationTime`); danach ergibt der Abruf 404, und der Beleg ist im Dashboard erneut freizugeben.
expirationTime* object
**Anderes Format als in der Auskunft — beides ist so gewollt.** Hier steht wie bei jedem Zeitstempel eines Ereignisses ein `LocalDateTime`: ISO 8601 in UTC, OHNE Zonenangabe und sekundengenau (`2026-09-19T14:38:22`). Dieselbe Frist liefert `GET …/orders/{orderId}` als vollständigen ISO-Zeitstempel MIT Zone und Millisekunden (`2026-09-19T14:38:22.558Z`). Der Zeitpunkt ist derselbe; wer beide Quellen vergleicht, muss den Wert des Ereignisses als UTC lesen. Das Format des Ereignisses folgt dem Vorbild kennzeichen.dev und bleibt deshalb, wie es ist.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden. Derselbe Wert wie in der Vorgangsauskunft.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709). **Nur bei eigener KBA-Registrierung** (Selbstabrechner): Ein Vertragspartner unter unserer Registrierung bekommt die amtlichen Beträge nicht zugestellt — er sieht sie auch in Auskunft und Dashboard nicht und bezahlt unsere Rechnung. Derselbe Wert steht als `costBreakdown` in der Vorgangsauskunft (`GET …/orders/{orderId}`), für den Abgleich nach einem verlorenen Ereignis.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
messages VehicleDeregistrationXkfzEventWebhookEventMessage[]
Die Meldungen des KBA (Quittungscode, Klartext, Zusatz). Nicht verpflichtend: Gibt es keine — der Regelfall beim Erfolg —, FEHLT das Feld im Ereignis. Die Vorgangsauskunft (`GET …/orders/{orderId}`) fuehrt an derselben Stelle ein leeres Array. Wer beide Quellen liest, behandelt „fehlt", `null` und `[]` gleich.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
applicationId string
Antragsnummer des KBA, 20-stellig.
licensePlate string
Das Kennzeichen des Vorgangs in Anzeigeform (`KBA-NZ 123`) — derselbe Wert wie `licensePlate` in der Vorgangsauskunft. Bei Vorfällen, die ein Kennzeichen zuteilen (NZ, TZ, UG, WG, WZ), steht hier nach dem Bescheid das zugeteilte. `registrationData.Kennzeichen` führt es dagegen in der Drahtform des KBA (`KBANZ 123`) und nur, wenn die Zulassungsdaten angefordert wurden. Fehlt, solange der Vorgang keines trägt.
retryable boolean
Gesetzt, wenn der Vorgang nur **vorübergehend** gescheitert ist — etwa weil das i-Kfz-Portal ausgefallen war oder der Zuständigkeitsfinder nicht antwortete. Derselbe Antrag hat später Aussicht auf Erfolg. Nur ein Hinweis, keine Zusage: Ob der Antrag beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Wer selbsttätig erneut sendet, riskiert die Doppelzulassung.
registrationData object
Die strukturierten Zulassungsdaten, sofern der Antrag sie über `requestRegistrationData` angefordert hat und das KBA sie geliefert hat — über sechzig Angaben aus den Zulassungsbescheinigungen (Kennzeichen, Erstzulassung, Fahrzeugklasse, Hubraum, CO2-Werte, Massen, Achslasten, Bereifung, Termin der nächsten Hauptuntersuchung). Die Feldnamen sind die des XKfz-Standards.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev — der Vertrag des Vorbilds kennt das Feld nicht. Es kommt zusätzlich und ist optional; ein bestehender Empfänger merkt davon nichts. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen — Zulassungsbescheinigung Teil I und Teil II, Stempelplaketten, Feinstaubplakette — wie gewünscht versandt wurden oder zur Abholung bereitliegen. Derselbe Wert steht in der Vorgangsauskunft (`GET …/orders/{orderId}`). Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung; eine Außerbetriebsetzung führt die Angabe nicht. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Sie entscheidet auch nichts: Ob der Antrag durch ist, sagen `status` und `derivedStatus`.
parties VehicleDeregistrationXkfzEventWebhookEventParty[]
Die Beteiligten aus dem Rückkanal — vor allem der Halter.
role* string
Codeliste `rolle`; `2` ist der Halter.
roleName string
Klartext der Rolle aus der Codeliste `rolle`, etwa `Halter`. Fehlt, wenn die Nachricht keinen führt.
kind* enum
natürliche Person, juristische Person, Vereinigung.
natural · legal · association
name* string
representative string
Nur bei einer Vereinigung (z. B. GbR) und nur, wenn die Nachricht einen führt — der benannte Vertreter, eine natürliche oder juristische Person. Seit XKfz 6.0 optional; fehlt er, fehlt das Feld.
{
  "eventType": "VEHICLE_HOLDER_CHANGE_XKFZ_EVENT",
  "order": {
    "id": 1001,
    "externalId": "bestellung-4712"
  },
  "status": "APPROVED_WITH_DOCUMENTS",
  "derivedStatus": "SUCCESS",
  "applicationId": "88888020240510000004",
  "files": [
    {
      "purposeType": "CERTIFICATE",
      "mediaType": "application/pdf",
      "fileAccessKey": "1001_11111111-1111-1111-1111-111111111111_0",
      "expirationTime": "2026-07-23T09:15:30"
    }
  ],
  "eventTime": "2026-07-20T09:15:30"
}
TYPVehicleTransferXkfzEventWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
attemptOf integer
Der **Auftrag**, zu dem dieses Ereignis gehört — beim ersten Versuch die eigene Id. **Ordnen Sie hierüber zu, nicht über `order.id`.** Wird ein abgewiesener Antrag korrigiert, entsteht beim KBA ein zweiter Antrag; das Ereignis dazu trägt dessen Id. Diese Id kommt in `GET …/orders` **nicht** vor — die Liste führt nur Auftragsköpfe. Wer Ereignisse über `order.id` zuordnet, legt damit einen Auftrag an, den er über die Liste nie wiederfindet. Das ist kein Randfall: Es passiert auch dem, der die volle Zustellhistorie vor sich hat und Ereignisse ausdrücklich zuordnen will.
attempt integer
Laufende Nummer des Versuchs. `1` beim ersten Antrag, `2` nach der ersten Korrektur.
order* object
id* integer (int64)
externalId string
businessTransaction enum
Der Geschäftsvorfall des Vorgangs — derselbe Wert wie `businessTransaction` in der Vorgangsauskunft. NZ und TZ teilen sich den Ereignistyp, WG und WZ ebenso; an diesem Feld erkennen Sie, welcher Vorfall beschieden wurde — auch bei Anträgen, die nicht über Ihre Schnittstelle, sondern über das Dashboard (Formular, Stapel, Korrektur) gestellt wurden.
AB · HA · UG · WG · WZ · NZ · TZ
status* VehicleDeregistrationXkfzEventWebhookEventStatus
derivedStatus* enum
Fachliche Einordnung im Vokabular von kennzeichen.dev. PENDING/SUCCESS/FAILURE sind Schwebe, Erfolg und nicht einordenbare Ablehnung; die uebrigen Werte benennen die Ablehnungsart, aus der ein Empfaenger Kundenaktion und Korrekturmaske ableitet. RESERVATION_IMPOSSIBLE — eine Kennzeichenreservierung ist nach Kennzeichenmitnahme nicht moeglich (Quittung 00764 mit entsprechendem Zusatz); ohne Reservierung neu einreichen. ERROR_UNHANDLED — NUR bei der Ausserbetriebsetzung (AB): Die Schemapruefung des KBA hat den Antrag an Registerdaten abgewiesen (00300 Namensbestandteile, 00301 Halter fehlt); dort senden wir keinen Halter, und weder Kundenkorrektur noch erneutes Einreichen helfen, der Fall gehoert in die manuelle Pruefung. Bei allen anderen Vorfaellen (HA, UG, WG, WZ, NZ, TZ) kommt eine Schemapruefung als FAILURE — sie ist dort ein Eingabefehler, der Grund steht in `messages[].additional` (Praefix `SCHEMAPRUEFUNG`), und der Antrag ist zu korrigieren. Beide Werte sendet dieses System seit dem 07.09.2026; sie standen bis zum 12.09.2026 nicht in diesem Vertrag. INPUT_INVALID — derzeit nicht gesendet; aus Kompatibilitätsgründen im Wertebereich. Eine Ablehnung, die die Zulassungsbehoerde im Bescheid (0709) begruendet — etwa Steuer- oder Gebuehrenrueckstaende —, hat kein eigenes Wort und kommt als FAILURE; die Gruende stehen in `messages` (Code und Klartext der Codeliste `ablehnungsgrund`).
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
files VehicleDeregistrationXkfzEventWebhookEventFile[]
purposeType* VehicleDeregistrationXkfzEventWebhookEventFilePurposeType
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}. Der Schlüssel eines Vorgangsbelegs gilt 72 Stunden ab dem Ablegen (`expirationTime`); danach ergibt der Abruf 404, und der Beleg ist im Dashboard erneut freizugeben.
expirationTime* object
**Anderes Format als in der Auskunft — beides ist so gewollt.** Hier steht wie bei jedem Zeitstempel eines Ereignisses ein `LocalDateTime`: ISO 8601 in UTC, OHNE Zonenangabe und sekundengenau (`2026-09-19T14:38:22`). Dieselbe Frist liefert `GET …/orders/{orderId}` als vollständigen ISO-Zeitstempel MIT Zone und Millisekunden (`2026-09-19T14:38:22.558Z`). Der Zeitpunkt ist derselbe; wer beide Quellen vergleicht, muss den Wert des Ereignisses als UTC lesen. Das Format des Ereignisses folgt dem Vorbild kennzeichen.dev und bleibt deshalb, wie es ist.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden. Derselbe Wert wie in der Vorgangsauskunft.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709). **Nur bei eigener KBA-Registrierung** (Selbstabrechner): Ein Vertragspartner unter unserer Registrierung bekommt die amtlichen Beträge nicht zugestellt — er sieht sie auch in Auskunft und Dashboard nicht und bezahlt unsere Rechnung. Derselbe Wert steht als `costBreakdown` in der Vorgangsauskunft (`GET …/orders/{orderId}`), für den Abgleich nach einem verlorenen Ereignis.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
messages VehicleDeregistrationXkfzEventWebhookEventMessage[]
Die Meldungen des KBA (Quittungscode, Klartext, Zusatz). Nicht verpflichtend: Gibt es keine — der Regelfall beim Erfolg —, FEHLT das Feld im Ereignis. Die Vorgangsauskunft (`GET …/orders/{orderId}`) fuehrt an derselben Stelle ein leeres Array. Wer beide Quellen liest, behandelt „fehlt", `null` und `[]` gleich.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
applicationId string
Antragsnummer des KBA, 20-stellig.
licensePlate string
Das Kennzeichen des Vorgangs in Anzeigeform (`KBA-NZ 123`) — derselbe Wert wie `licensePlate` in der Vorgangsauskunft. Bei Vorfällen, die ein Kennzeichen zuteilen (NZ, TZ, UG, WG, WZ), steht hier nach dem Bescheid das zugeteilte. `registrationData.Kennzeichen` führt es dagegen in der Drahtform des KBA (`KBANZ 123`) und nur, wenn die Zulassungsdaten angefordert wurden. Fehlt, solange der Vorgang keines trägt.
retryable boolean
Gesetzt, wenn der Vorgang nur **vorübergehend** gescheitert ist — etwa weil das i-Kfz-Portal ausgefallen war oder der Zuständigkeitsfinder nicht antwortete. Derselbe Antrag hat später Aussicht auf Erfolg. Nur ein Hinweis, keine Zusage: Ob der Antrag beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Wer selbsttätig erneut sendet, riskiert die Doppelzulassung.
registrationData object
Die strukturierten Zulassungsdaten, sofern der Antrag sie über `requestRegistrationData` angefordert hat und das KBA sie geliefert hat — über sechzig Angaben aus den Zulassungsbescheinigungen (Kennzeichen, Erstzulassung, Fahrzeugklasse, Hubraum, CO2-Werte, Massen, Achslasten, Bereifung, Termin der nächsten Hauptuntersuchung). Die Feldnamen sind die des XKfz-Standards.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev — der Vertrag des Vorbilds kennt das Feld nicht. Es kommt zusätzlich und ist optional; ein bestehender Empfänger merkt davon nichts. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen — Zulassungsbescheinigung Teil I und Teil II, Stempelplaketten, Feinstaubplakette — wie gewünscht versandt wurden oder zur Abholung bereitliegen. Derselbe Wert steht in der Vorgangsauskunft (`GET …/orders/{orderId}`). Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung; eine Außerbetriebsetzung führt die Angabe nicht. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Sie entscheidet auch nichts: Ob der Antrag durch ist, sagen `status` und `derivedStatus`.
parties VehicleDeregistrationXkfzEventWebhookEventParty[]
Die Beteiligten aus dem Rückkanal — vor allem der Halter.
role* string
Codeliste `rolle`; `2` ist der Halter.
roleName string
Klartext der Rolle aus der Codeliste `rolle`, etwa `Halter`. Fehlt, wenn die Nachricht keinen führt.
kind* enum
natürliche Person, juristische Person, Vereinigung.
natural · legal · association
name* string
representative string
Nur bei einer Vereinigung (z. B. GbR) und nur, wenn die Nachricht einen führt — der benannte Vertreter, eine natürliche oder juristische Person. Seit XKfz 6.0 optional; fehlt er, fehlt das Feld.
{
  "eventType": "VEHICLE_TRANSFER_XKFZ_EVENT",
  "order": {
    "id": 1002,
    "externalId": "bestellung-4713"
  },
  "status": "FORWARDED",
  "derivedStatus": "PENDING",
  "applicationId": "88888020240510000005",
  "messages": [
    {
      "type": "QUITTUNG",
      "kind": "Hinweis",
      "code": "00775",
      "text": "Der Antrag wurde zur manuellen Bearbeitung ausgesteuert."
    }
  ],
  "eventTime": "2026-07-20T09:15:30"
}
TYPVehicleReRegistrationXkfzEventWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
attemptOf integer
Der **Auftrag**, zu dem dieses Ereignis gehört — beim ersten Versuch die eigene Id. **Ordnen Sie hierüber zu, nicht über `order.id`.** Wird ein abgewiesener Antrag korrigiert, entsteht beim KBA ein zweiter Antrag; das Ereignis dazu trägt dessen Id. Diese Id kommt in `GET …/orders` **nicht** vor — die Liste führt nur Auftragsköpfe. Wer Ereignisse über `order.id` zuordnet, legt damit einen Auftrag an, den er über die Liste nie wiederfindet. Das ist kein Randfall: Es passiert auch dem, der die volle Zustellhistorie vor sich hat und Ereignisse ausdrücklich zuordnen will.
attempt integer
Laufende Nummer des Versuchs. `1` beim ersten Antrag, `2` nach der ersten Korrektur.
order* object
id* integer (int64)
externalId string
businessTransaction enum
Der Geschäftsvorfall des Vorgangs — derselbe Wert wie `businessTransaction` in der Vorgangsauskunft. NZ und TZ teilen sich den Ereignistyp, WG und WZ ebenso; an diesem Feld erkennen Sie, welcher Vorfall beschieden wurde — auch bei Anträgen, die nicht über Ihre Schnittstelle, sondern über das Dashboard (Formular, Stapel, Korrektur) gestellt wurden.
AB · HA · UG · WG · WZ · NZ · TZ
status* VehicleDeregistrationXkfzEventWebhookEventStatus
derivedStatus* enum
Fachliche Einordnung im Vokabular von kennzeichen.dev. PENDING/SUCCESS/FAILURE sind Schwebe, Erfolg und nicht einordenbare Ablehnung; die uebrigen Werte benennen die Ablehnungsart, aus der ein Empfaenger Kundenaktion und Korrekturmaske ableitet. RESERVATION_IMPOSSIBLE — eine Kennzeichenreservierung ist nach Kennzeichenmitnahme nicht moeglich (Quittung 00764 mit entsprechendem Zusatz); ohne Reservierung neu einreichen. ERROR_UNHANDLED — NUR bei der Ausserbetriebsetzung (AB): Die Schemapruefung des KBA hat den Antrag an Registerdaten abgewiesen (00300 Namensbestandteile, 00301 Halter fehlt); dort senden wir keinen Halter, und weder Kundenkorrektur noch erneutes Einreichen helfen, der Fall gehoert in die manuelle Pruefung. Bei allen anderen Vorfaellen (HA, UG, WG, WZ, NZ, TZ) kommt eine Schemapruefung als FAILURE — sie ist dort ein Eingabefehler, der Grund steht in `messages[].additional` (Praefix `SCHEMAPRUEFUNG`), und der Antrag ist zu korrigieren. Beide Werte sendet dieses System seit dem 07.09.2026; sie standen bis zum 12.09.2026 nicht in diesem Vertrag. INPUT_INVALID — derzeit nicht gesendet; aus Kompatibilitätsgründen im Wertebereich. Eine Ablehnung, die die Zulassungsbehoerde im Bescheid (0709) begruendet — etwa Steuer- oder Gebuehrenrueckstaende —, hat kein eigenes Wort und kommt als FAILURE; die Gruende stehen in `messages` (Code und Klartext der Codeliste `ablehnungsgrund`).
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
files VehicleDeregistrationXkfzEventWebhookEventFile[]
purposeType* VehicleDeregistrationXkfzEventWebhookEventFilePurposeType
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}. Der Schlüssel eines Vorgangsbelegs gilt 72 Stunden ab dem Ablegen (`expirationTime`); danach ergibt der Abruf 404, und der Beleg ist im Dashboard erneut freizugeben.
expirationTime* object
**Anderes Format als in der Auskunft — beides ist so gewollt.** Hier steht wie bei jedem Zeitstempel eines Ereignisses ein `LocalDateTime`: ISO 8601 in UTC, OHNE Zonenangabe und sekundengenau (`2026-09-19T14:38:22`). Dieselbe Frist liefert `GET …/orders/{orderId}` als vollständigen ISO-Zeitstempel MIT Zone und Millisekunden (`2026-09-19T14:38:22.558Z`). Der Zeitpunkt ist derselbe; wer beide Quellen vergleicht, muss den Wert des Ereignisses als UTC lesen. Das Format des Ereignisses folgt dem Vorbild kennzeichen.dev und bleibt deshalb, wie es ist.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden. Derselbe Wert wie in der Vorgangsauskunft.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709). **Nur bei eigener KBA-Registrierung** (Selbstabrechner): Ein Vertragspartner unter unserer Registrierung bekommt die amtlichen Beträge nicht zugestellt — er sieht sie auch in Auskunft und Dashboard nicht und bezahlt unsere Rechnung. Derselbe Wert steht als `costBreakdown` in der Vorgangsauskunft (`GET …/orders/{orderId}`), für den Abgleich nach einem verlorenen Ereignis.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
messages VehicleDeregistrationXkfzEventWebhookEventMessage[]
Die Meldungen des KBA (Quittungscode, Klartext, Zusatz). Nicht verpflichtend: Gibt es keine — der Regelfall beim Erfolg —, FEHLT das Feld im Ereignis. Die Vorgangsauskunft (`GET …/orders/{orderId}`) fuehrt an derselben Stelle ein leeres Array. Wer beide Quellen liest, behandelt „fehlt", `null` und `[]` gleich.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
applicationId string
Antragsnummer des KBA, 20-stellig.
licensePlate string
Das Kennzeichen des Vorgangs in Anzeigeform (`KBA-NZ 123`) — derselbe Wert wie `licensePlate` in der Vorgangsauskunft. Bei Vorfällen, die ein Kennzeichen zuteilen (NZ, TZ, UG, WG, WZ), steht hier nach dem Bescheid das zugeteilte. `registrationData.Kennzeichen` führt es dagegen in der Drahtform des KBA (`KBANZ 123`) und nur, wenn die Zulassungsdaten angefordert wurden. Fehlt, solange der Vorgang keines trägt.
retryable boolean
Gesetzt, wenn der Vorgang nur **vorübergehend** gescheitert ist — etwa weil das i-Kfz-Portal ausgefallen war oder der Zuständigkeitsfinder nicht antwortete. Derselbe Antrag hat später Aussicht auf Erfolg. Nur ein Hinweis, keine Zusage: Ob der Antrag beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Wer selbsttätig erneut sendet, riskiert die Doppelzulassung.
registrationData object
Die strukturierten Zulassungsdaten, sofern der Antrag sie über `requestRegistrationData` angefordert hat und das KBA sie geliefert hat — über sechzig Angaben aus den Zulassungsbescheinigungen (Kennzeichen, Erstzulassung, Fahrzeugklasse, Hubraum, CO2-Werte, Massen, Achslasten, Bereifung, Termin der nächsten Hauptuntersuchung). Die Feldnamen sind die des XKfz-Standards.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev — der Vertrag des Vorbilds kennt das Feld nicht. Es kommt zusätzlich und ist optional; ein bestehender Empfänger merkt davon nichts. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen — Zulassungsbescheinigung Teil I und Teil II, Stempelplaketten, Feinstaubplakette — wie gewünscht versandt wurden oder zur Abholung bereitliegen. Derselbe Wert steht in der Vorgangsauskunft (`GET …/orders/{orderId}`). Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung; eine Außerbetriebsetzung führt die Angabe nicht. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Sie entscheidet auch nichts: Ob der Antrag durch ist, sagen `status` und `derivedStatus`.
parties VehicleDeregistrationXkfzEventWebhookEventParty[]
Die Beteiligten aus dem Rückkanal — vor allem der Halter.
role* string
Codeliste `rolle`; `2` ist der Halter.
roleName string
Klartext der Rolle aus der Codeliste `rolle`, etwa `Halter`. Fehlt, wenn die Nachricht keinen führt.
kind* enum
natürliche Person, juristische Person, Vereinigung.
natural · legal · association
name* string
representative string
Nur bei einer Vereinigung (z. B. GbR) und nur, wenn die Nachricht einen führt — der benannte Vertreter, eine natürliche oder juristische Person. Seit XKfz 6.0 optional; fehlt er, fehlt das Feld.
{
  "eventType": "VEHICLE_REREGISTRATION_XKFZ_EVENT",
  "order": {
    "id": 1003,
    "externalId": "bestellung-4714"
  },
  "status": "APPROVED_WITH_DOCUMENTS",
  "derivedStatus": "SUCCESS",
  "applicationId": "88888020240510000006",
  "files": [
    {
      "purposeType": "CERTIFICATE",
      "mediaType": "application/pdf",
      "fileAccessKey": "1003_11111111-1111-1111-1111-111111111111_0",
      "expirationTime": "2026-07-23T09:15:30"
    }
  ],
  "eventTime": "2026-07-20T09:15:30"
}
TYPVehicleRegistrationXkfzEventWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
attemptOf integer
Der **Auftrag**, zu dem dieses Ereignis gehört — beim ersten Versuch die eigene Id. **Ordnen Sie hierüber zu, nicht über `order.id`.** Wird ein abgewiesener Antrag korrigiert, entsteht beim KBA ein zweiter Antrag; das Ereignis dazu trägt dessen Id. Diese Id kommt in `GET …/orders` **nicht** vor — die Liste führt nur Auftragsköpfe. Wer Ereignisse über `order.id` zuordnet, legt damit einen Auftrag an, den er über die Liste nie wiederfindet. Das ist kein Randfall: Es passiert auch dem, der die volle Zustellhistorie vor sich hat und Ereignisse ausdrücklich zuordnen will.
attempt integer
Laufende Nummer des Versuchs. `1` beim ersten Antrag, `2` nach der ersten Korrektur.
order* object
id* integer (int64)
externalId string
businessTransaction enum
Der Geschäftsvorfall des Vorgangs — derselbe Wert wie `businessTransaction` in der Vorgangsauskunft. NZ und TZ teilen sich den Ereignistyp, WG und WZ ebenso; an diesem Feld erkennen Sie, welcher Vorfall beschieden wurde — auch bei Anträgen, die nicht über Ihre Schnittstelle, sondern über das Dashboard (Formular, Stapel, Korrektur) gestellt wurden.
AB · HA · UG · WG · WZ · NZ · TZ
status* VehicleDeregistrationXkfzEventWebhookEventStatus
derivedStatus* enum
Fachliche Einordnung im Vokabular von kennzeichen.dev. PENDING/SUCCESS/FAILURE sind Schwebe, Erfolg und nicht einordenbare Ablehnung; die uebrigen Werte benennen die Ablehnungsart, aus der ein Empfaenger Kundenaktion und Korrekturmaske ableitet. RESERVATION_IMPOSSIBLE — eine Kennzeichenreservierung ist nach Kennzeichenmitnahme nicht moeglich (Quittung 00764 mit entsprechendem Zusatz); ohne Reservierung neu einreichen. ERROR_UNHANDLED — NUR bei der Ausserbetriebsetzung (AB): Die Schemapruefung des KBA hat den Antrag an Registerdaten abgewiesen (00300 Namensbestandteile, 00301 Halter fehlt); dort senden wir keinen Halter, und weder Kundenkorrektur noch erneutes Einreichen helfen, der Fall gehoert in die manuelle Pruefung. Bei allen anderen Vorfaellen (HA, UG, WG, WZ, NZ, TZ) kommt eine Schemapruefung als FAILURE — sie ist dort ein Eingabefehler, der Grund steht in `messages[].additional` (Praefix `SCHEMAPRUEFUNG`), und der Antrag ist zu korrigieren. Beide Werte sendet dieses System seit dem 07.09.2026; sie standen bis zum 12.09.2026 nicht in diesem Vertrag. INPUT_INVALID — derzeit nicht gesendet; aus Kompatibilitätsgründen im Wertebereich. Eine Ablehnung, die die Zulassungsbehoerde im Bescheid (0709) begruendet — etwa Steuer- oder Gebuehrenrueckstaende —, hat kein eigenes Wort und kommt als FAILURE; die Gruende stehen in `messages` (Code und Klartext der Codeliste `ablehnungsgrund`).
PENDING · SUCCESS · FAILURE · VEHICLE_UNKNOWN · VEHICLE_ALREADY_DEREGISTERED · LICENSE_PLATE_CODE_INVALID · REGISTRATION_CERTIFICATE_CODE_INVALID · LICENSE_PLATE_CODE_QTY_INVALID · INPUT_INVALID · RESERVATION_IMPOSSIBLE · ERROR_UNHANDLED
files VehicleDeregistrationXkfzEventWebhookEventFile[]
purposeType* VehicleDeregistrationXkfzEventWebhookEventFilePurposeType
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}. Der Schlüssel eines Vorgangsbelegs gilt 72 Stunden ab dem Ablegen (`expirationTime`); danach ergibt der Abruf 404, und der Beleg ist im Dashboard erneut freizugeben.
expirationTime* object
**Anderes Format als in der Auskunft — beides ist so gewollt.** Hier steht wie bei jedem Zeitstempel eines Ereignisses ein `LocalDateTime`: ISO 8601 in UTC, OHNE Zonenangabe und sekundengenau (`2026-09-19T14:38:22`). Dieselbe Frist liefert `GET …/orders/{orderId}` als vollständigen ISO-Zeitstempel MIT Zone und Millisekunden (`2026-09-19T14:38:22.558Z`). Der Zeitpunkt ist derselbe; wer beide Quellen vergleicht, muss den Wert des Ereignisses als UTC lesen. Das Format des Ereignisses folgt dem Vorbild kennzeichen.dev und bleibt deshalb, wie es ist.
filename string
Der Name, unter dem der Abruf die Datei ausliefert (`Content-Disposition`), z. B. `Vorgang-17_KBA-NZ-123_Zulassungsbescheid.pdf`. Zwei Belege mit `purposeType: CERTIFICATE` — Zulassungsbescheid und vorläufiger Zulassungsnachweis — sind daran zu unterscheiden. Derselbe Wert wie in der Vorgangsauskunft.
costBreakdown object
Die Gebührenaufstellung aus der Entscheidung (0709). **Nur bei eigener KBA-Registrierung** (Selbstabrechner): Ein Vertragspartner unter unserer Registrierung bekommt die amtlichen Beträge nicht zugestellt — er sieht sie auch in Auskunft und Dashboard nicht und bezahlt unsere Rechnung. Derselbe Wert steht als `costBreakdown` in der Vorgangsauskunft (`GET …/orders/{orderId}`), für den Abgleich nach einem verlorenen Ereignis.
kbaCost integer
Nutzungsgebühr des KBA nach Nr. 129 GebOSt, in Cent. Steht da, wenn das KBA sie mit Quittungscode 07085 angekündigt hat oder der Antrag beschieden bzw. abgelehnt ist; sonst fehlt das Feld.
registrationOfficeCosts object
items* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
total* VehicleDeregistrationXkfzEventWebhookEventCostBreakdownItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in kleinster Währungseinheit (Cent).
note string
messages VehicleDeregistrationXkfzEventWebhookEventMessage[]
Die Meldungen des KBA (Quittungscode, Klartext, Zusatz). Nicht verpflichtend: Gibt es keine — der Regelfall beim Erfolg —, FEHLT das Feld im Ereignis. Die Vorgangsauskunft (`GET …/orders/{orderId}`) fuehrt an derselben Stelle ein leeres Array. Wer beide Quellen liest, behandelt „fehlt", `null` und `[]` gleich.
type* string
Herkunft der Meldung — `QUITTUNG` für jede Meldung des KBA, aus der Quittung (0002) wie aus der Entscheidung (0709).
kind enum
Quittungsart in Worten (Codeliste quittungsart 0/1/2). Fehlt bei den Ablehnungsgründen der 0709 — sie tragen keine Quittungsart.
Hinweis · Warnung · Fehler
code string
**Nicht immer fünfstellig.** Drei Ausprägungen kommen vor: der fünfstellige Quittungscode des KBA (`07077`); der kurze, numerische Ablehnungsgrund der 0709 (Codeliste `grundablehnungzulassungsantrag`, etwa `1` für Steuerrückstände, `2` für Gebührenrückstände); und — bei einer Ablehnung ohne Ablehnungsgrund, dem Regelfall — der Antragsstatus in Worten (Codeliste `statuselektronischerantrag`: neu, geprueft, wartend, weitergeleitet, bearbeitet, abgeschlossen, abgelehnt, eskaliert). Prüfen Sie den Wert nicht auf fünf Stellen.
text string
additional string
applicationId string
Antragsnummer des KBA, 20-stellig.
licensePlate string
Das Kennzeichen des Vorgangs in Anzeigeform (`KBA-NZ 123`) — derselbe Wert wie `licensePlate` in der Vorgangsauskunft. Bei Vorfällen, die ein Kennzeichen zuteilen (NZ, TZ, UG, WG, WZ), steht hier nach dem Bescheid das zugeteilte. `registrationData.Kennzeichen` führt es dagegen in der Drahtform des KBA (`KBANZ 123`) und nur, wenn die Zulassungsdaten angefordert wurden. Fehlt, solange der Vorgang keines trägt.
retryable boolean
Gesetzt, wenn der Vorgang nur **vorübergehend** gescheitert ist — etwa weil das i-Kfz-Portal ausgefallen war oder der Zuständigkeitsfinder nicht antwortete. Derselbe Antrag hat später Aussicht auf Erfolg. Nur ein Hinweis, keine Zusage: Ob der Antrag beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Wer selbsttätig erneut sendet, riskiert die Doppelzulassung.
registrationData object
Die strukturierten Zulassungsdaten, sofern der Antrag sie über `requestRegistrationData` angefordert hat und das KBA sie geliefert hat — über sechzig Angaben aus den Zulassungsbescheinigungen (Kennzeichen, Erstzulassung, Fahrzeugklasse, Hubraum, CO2-Werte, Massen, Achslasten, Bereifung, Termin der nächsten Hauptuntersuchung). Die Feldnamen sind die des XKfz-Standards.
registrationDocumentsReady boolean
Erweiterung gegenüber kennzeichen.dev — der Vertrag des Vorbilds kennt das Feld nicht. Es kommt zusätzlich und ist optional; ein bestehender Empfänger merkt davon nichts. `true`, wenn die Zulassungsbehörde meldet, dass die Zulassungsunterlagen — Zulassungsbescheinigung Teil I und Teil II, Stempelplaketten, Feinstaubplakette — wie gewünscht versandt wurden oder zur Abholung bereitliegen. Derselbe Wert steht in der Vorgangsauskunft (`GET …/orders/{orderId}`). Nur bei Zulassungsvorfällen und nur in der automatisierten Bearbeitung nach einer antragsgemäßen Entscheidung; eine Außerbetriebsetzung führt die Angabe nicht. **Fehlt das Feld, ist nichts gesagt** — nicht „nicht versandt": Die Behörde führt die Angabe nicht in jeder Nachricht. Sie entscheidet auch nichts: Ob der Antrag durch ist, sagen `status` und `derivedStatus`.
parties VehicleDeregistrationXkfzEventWebhookEventParty[]
Die Beteiligten aus dem Rückkanal — vor allem der Halter.
role* string
Codeliste `rolle`; `2` ist der Halter.
roleName string
Klartext der Rolle aus der Codeliste `rolle`, etwa `Halter`. Fehlt, wenn die Nachricht keinen führt.
kind* enum
natürliche Person, juristische Person, Vereinigung.
natural · legal · association
name* string
representative string
Nur bei einer Vereinigung (z. B. GbR) und nur, wenn die Nachricht einen führt — der benannte Vertreter, eine natürliche oder juristische Person. Seit XKfz 6.0 optional; fehlt er, fehlt das Feld.
{
  "eventType": "VEHICLE_REGISTRATION_XKFZ_EVENT",
  "order": {
    "id": 1004,
    "externalId": "bestellung-4715"
  },
  "status": "REJECTED",
  "derivedStatus": "FAILURE",
  "applicationId": "88888020240510000007",
  "messages": [
    {
      "type": "QUITTUNG",
      "kind": "Fehler",
      "code": "99996",
      "text": "Der Antrag wurde abgelehnt.",
      "additional": "Die Prüfung der eVB-Nummer ist negativ verlaufen."
    }
  ],
  "eventTime": "2026-07-20T09:15:30"
}
TYPDeliveryShipmentWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "DELIVERY_SHIPMENT",
  "delivery": {
    "id": 2000,
    "trackingCode": "01234567890123456789"
  },
  "order": {
    "id": 1000,
    "externalId": "ext-1"
  },
  "eventTime": "2026-07-20T09:15:30"
}
TYPDeliveryReturnWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "DELIVERY_RETURN",
  "delivery": {
    "id": 2000
  },
  "order": {
    "id": 1000,
    "externalId": "ext-1"
  },
  "returnReason": "Empfänger nicht zu ermitteln / Unbekannt verzogen",
  "reshippingOfferExpirationDate": "2026-11-06",
  "eventTime": "2026-07-20T09:15:30"
}
TYPDeliveryCancellationWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "DELIVERY_CANCELLATION",
  "delivery": {
    "id": 2000
  },
  "order": {
    "id": 1000,
    "externalId": "ext-1"
  },
  "eventTime": "2026-07-20T09:15:30"
}
TYPLicencePlateReservationApprovalWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "LICENSE_PLATE_RESERVATION_APPROVAL",
  "order": {
    "id": 1000,
    "externalId": "ext-1"
  },
  "reservationPin": "PIN123",
  "customization": {
    "registrationOfficeServiceId": 1,
    "licensePlateNumberComponents": {
      "usageType": "EURO",
      "city": "AB",
      "middle": "CD",
      "end": "123"
    },
    "licensePlateType": "REGULAR_SEASON",
    "vehicleType": "CAR",
    "seasonStartMonth": 4,
    "seasonEndMonth": 10
  },
  "reservationPrice": "0.00",
  "eventTime": "2026-07-20T09:15:30"
}
TYPLicencePlateReservationRejectionWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "LICENSE_PLATE_RESERVATION_REJECTION",
  "order": {
    "id": 1000,
    "externalId": "ext-1"
  },
  "customization": {
    "registrationOfficeServiceId": 1,
    "licensePlateNumberComponents": {
      "usageType": "EURO",
      "city": "AB",
      "middle": "CD",
      "end": "123"
    },
    "licensePlateType": "REGULAR_SEASON",
    "vehicleType": "CAR",
    "seasonStartMonth": 4,
    "seasonEndMonth": 10
  },
  "proposedAlternativeLicensePlateNumberComponents": [
    {
      "usageType": "EURO",
      "city": "AB",
      "middle": "CD",
      "end": "124"
    },
    {
      "usageType": "EURO",
      "city": "AB",
      "middle": "CD",
      "end": "125"
    }
  ],
  "eventTime": "2026-07-20T09:15:30"
}
TYPLicencePlateReservationTimeoutWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "LICENSE_PLATE_RESERVATION_TIMEOUT",
  "order": {
    "id": 1000,
    "externalId": "ext-1"
  },
  "customization": {
    "registrationOfficeServiceId": 1,
    "licensePlateNumberComponents": {
      "usageType": "EURO",
      "city": "AB",
      "middle": "CD",
      "end": "123"
    },
    "licensePlateType": "REGULAR_SEASON",
    "vehicleType": "CAR",
    "seasonStartMonth": 4,
    "seasonEndMonth": 10
  },
  "eventTime": "2026-07-20T09:15:30"
}
TYPEingangsFile
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601 in UTC, ohne Zonenangabe, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
TYPFeeNoticeItem
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
TYPFeeNoticeApplication
applicationId string
Antragsnummer des KBA, 20-stellig.
paymentId string
Kassenzeichen dieses Antrags (Referenztyp 12).
licensePlate string
vehicleIdentificationNumber string
applicationDate string
businessTransaction string
AB
amount* integer
Summe der Positionen in Cent.
items* FeeNoticeItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
assignment* enum
MATCHED — der Antrag gehört zu einem eigenen Vorgang (`order`). UNKNOWN — kein eigener Vorgang trägt diese Antragsnummer; kein Fehler, der Bescheid kann Anträge eines früheren Systems enthalten. AMBIGUOUS — die Antragsnummer steht mehrfach im Bescheid. MISMATCH — ein Vorgang trägt die Nummer, aber das Kennzeichen oder der Vertragspartner passt nicht.
MATCHED · UNKNOWN · AMBIGUOUS · MISMATCH
order object
id* integer (int64)
externalId string
contractPartner string
Kommunikationspartnerschlüssel des Vertragspartners, der den Antrag gestellt hat (Referenztyp 28), z. B. U234567 — nur, wenn die Behörde ihn nennt.
TYPFeeNotice
id* integer
messageId* string
Nachrichten-ID des KBA — eindeutig, auch bei erneuter Zustellung.
receivedAt* string
Wann die Nachricht hier ankam, ohne Zeitzone, sekundengenau.
issuedAt string
zeitpunktDerErstellung laut Nachrichtenkopf, wie das KBA ihn schreibt.
issuer* object
partnerKey* string
Kommunikationspartnerschlüssel der Zulassungsbehörde, z. B. B115779.
districtKey* string
Kreisschlüssel samt Zusatzziffer des Gebührengläubigers, z. B. 010010.
debtor* object
partnerKey* string
Kommunikationspartnerschlüssel des Gebührenschuldners — die eigene KoPa.
bank* object
accountHolder* string
iban* string
directDebit* boolean
true, wenn die Behörde per SEPA-Lastschrift einzieht — dann wird nicht überwiesen.
paymentReference string
Verwendungszweck laut Bescheid, meist Bescheidnummer und Kassenzeichen.
paymentId string
Kassenzeichen des Bescheids, sofern die Behörde eines eigens nennt.
dueDate string
amount* integer
Gesamtbetrag in Cent — der der Nachricht, nicht eine eigene Addition. Bei einem geteilten Bescheid die Summe sämtlicher Anträge aus der letzten Nachricht.
currency* string
noticeNumber string
Nummer des Gebührenbescheids laut Nachricht.
part object
Teil n von m laut Bescheidkopf (XKfz 6.0). Ab mehr als 500 Anträgen teilt die Behörde den Bescheid auf mehrere Nachrichten; nur die letzte trägt Gesamtbetrag, Bankverbindung, Kassenzeichen und PDF. Ein geteilter Bescheid erscheint deshalb nur einmal, mit seiner abschließenden Nachricht (der mit Gesamtbetrag), und `applications` enthält die Anträge aller bis dahin eingegangenen Teile. `part` gibt die Zählung laut Bescheidkopf wieder; sie kann auch eigenständige Bescheide eines Abrechnungszeitraums zählen, `part.number` muss also nicht `part.of` sein. Trifft ein früherer Teil erst danach ein, kommt das Ereignis erneut — mit derselben `id`, derselben `messageId`, demselben `amount` und der ergänzten Antragsliste.
number* integer
of* integer
applicationCount* integer
Anzahl der abgerechneten Anträge laut Nachricht; mindestens die Zahl der mitgeführten. Liegt sie über `applications`, fehlen noch Teile.
assignedCount* integer
Wie viele der Anträge zu einem eigenen Vorgang gehören.
applications* FeeNoticeApplication[]
applicationId string
Antragsnummer des KBA, 20-stellig.
paymentId string
Kassenzeichen dieses Antrags (Referenztyp 12).
licensePlate string
vehicleIdentificationNumber string
applicationDate string
businessTransaction string
AB
amount* integer
Summe der Positionen in Cent.
items* FeeNoticeItem[]
number* integer
code string
Gebührennummer nach GebOSt, z. B. 224.2.
name string
amount* integer
Betrag in Cent.
note string
assignment* enum
MATCHED — der Antrag gehört zu einem eigenen Vorgang (`order`). UNKNOWN — kein eigener Vorgang trägt diese Antragsnummer; kein Fehler, der Bescheid kann Anträge eines früheren Systems enthalten. AMBIGUOUS — die Antragsnummer steht mehrfach im Bescheid. MISMATCH — ein Vorgang trägt die Nummer, aber das Kennzeichen oder der Vertragspartner passt nicht.
MATCHED · UNKNOWN · AMBIGUOUS · MISMATCH
order object
id* integer (int64)
externalId string
contractPartner string
Kommunikationspartnerschlüssel des Vertragspartners, der den Antrag gestellt hat (Referenztyp 28), z. B. U234567 — nur, wenn die Behörde ihn nennt.
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601 in UTC, ohne Zonenangabe, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
TYPUnmatchedMessage
id* integer
messageType* string
Nachrichtentyp des KBA, z. B. 0709 (Antragskopie/Bescheid) oder 0002 (Quittung). **Ausschliesslich** Typen des KBA: Was dieses System nicht lesen konnte (unlesbare oder leere Antwort einer Zwischenstelle) oder woran seine Verarbeitung scheiterte, ist ein Betriebsvorfall bei uns — er wird roh bewahrt und dem Betreiber gemeldet, erzeugt aber weder eine Nachricht noch ein Ereignis.
messageId string
receivedAt* string
issuedAt string
issuer* object
partnerKey* string
recipient* object
partnerKey* string
applicationId string
vehicleIdentificationNumber string
licensePlate string
businessTransaction string
status string
Antragsstatus laut Nachricht, z. B. bearbeitet, abgelehnt oder — seit XKfz 6.0 in der finalen Zulassungsnachricht — abgeschlossen.
statusTime string
processingKind string
Bearbeitungsart laut Nachricht, z. B. A für automatisiert.
decision enum
APPROVED · REJECTED · UNKNOWN
messages object[]
Die Quittungseinträge, sofern die Nachricht eine Quittung ist.
state* enum
OPEN · HANDLED · IGNORED
order object
id* integer (int64)
files* EingangsFile[]
purposeType* enum
RECEIPT ist der Gebührenbescheid als PDF, UNSPECIFIED das XML der Nachricht.
CERTIFICATE · RECEIPT · APPLICATION · UNSPECIFIED
mediaType* string
fileAccessKey* string (password)
Einzulösen über GET /vehicleDeregistrations/files/content/{fileAccessKey}.
expirationTime* string
Zeitpunkt nach ISO 8601 in UTC, ohne Zonenangabe, sekundengenau. Die Schlüssel eines Sammelgebührenbescheids (`gb_…`) und einer Nachricht ohne Vorgang (`ek_…`) gelten 90 Tage ab dem Ablegen — nicht 72 Stunden wie ein Vorgangsbeleg. Die Einzelauskunft (GET /vehicleDeregistrations/feeNotices/{id}, GET /vehicleDeregistrations/unmatchedMessages/{id}) setzt die Frist neu an.
filename* string
Der Name, unter dem der Abruf die Datei ausliefert — nach dem Muster `Datum_Behörde_0|1_Kassenzeichen_Nachrichten-ID.xml|pdf`, wie es kennzeichen.dev verwendet hat.
TYPFeeNoticeXkfzEventWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "FEE_NOTICE_XKFZ_EVENT",
  "feeNotice": {
    "id": 12,
    "messageId": "78b26690-c2ac-4cd5-ae0a-19245e39f91a",
    "receivedAt": "2026-09-07T03:14:02",
    "issuedAt": "2026-09-07T03:12:35.619+02:00",
    "issuer": {
      "partnerKey": "B115779",
      "districtKey": "010010"
    },
    "debtor": {
      "partnerKey": "U203522"
    },
    "bank": {
      "accountHolder": "Kreisverwaltung Musterland",
      "iban": "DE64301502000001000504",
      "directDebit": false
    },
    "paymentReference": "2026091000001 / 029975-2026-SJ",
    "paymentId": "029975-2026-SJ",
    "dueDate": "2026-10-07T23:59:59+02:00",
    "amount": 660,
    "currency": "EUR",
    "noticeNumber": "2026091000001",
    "part": {
      "number": 1,
      "of": 1
    },
    "applicationCount": 2,
    "assignedCount": 1,
    "applications": [
      {
        "applicationId": "88888020260815000632",
        "paymentId": "027537-2026-HA",
        "licensePlate": "AW NI 40",
        "vehicleIdentificationNumber": "WBA3T1C58GP823856",
        "applicationDate": "2026-08-15",
        "businessTransaction": "AB",
        "amount": 330,
        "items": [
          {
            "number": 1,
            "code": "224.2",
            "name": "Außerbetriebsetzung internetbasiert",
            "amount": 210,
            "note": null
          },
          {
            "number": 2,
            "code": "125",
            "name": "Berichtigung ZFZR",
            "amount": 120,
            "note": null
          }
        ],
        "assignment": "MATCHED",
        "order": {
          "id": 376,
          "externalId": "bestellung-4711"
        },
        "contractPartner": null
      }
    ],
    "files": [
      {
        "purposeType": "RECEIPT",
        "mediaType": "application/pdf",
        "fileAccessKey": "gb_11111111-1111-1111-1111-111111111111_1",
        "expirationTime": "2026-12-06T03:14:02",
        "filename": "2026-09-07_B115779_1_029975-2026-SJ_78b26690-c2ac-4cd5-ae0a-19245e39f91a.pdf"
      },
      {
        "purposeType": "UNSPECIFIED",
        "mediaType": "text/xml",
        "fileAccessKey": "gb_11111111-1111-1111-1111-111111111111_0",
        "expirationTime": "2026-12-06T03:14:02",
        "filename": "2026-09-07_B115779_0_029975-2026-SJ_78b26690-c2ac-4cd5-ae0a-19245e39f91a.xml"
      }
    ]
  },
  "eventTime": "2026-09-07T03:14:02"
}
TYPUnmatchedMessageXkfzEventWebhookEvent
eventType* WebhookEventType
eventTime* LocalDateTime
{
  "eventType": "UNMATCHED_MESSAGE_XKFZ_EVENT",
  "message": {
    "id": 5,
    "messageType": "0709",
    "messageId": "7ed883d4-7f45-4a62-9063-76cccad17aa8",
    "receivedAt": "2026-09-09T06:21:26",
    "issuedAt": "2026-09-09T08:20:28.185+02:00",
    "issuer": {
      "partnerKey": "B111012"
    },
    "recipient": {
      "partnerKey": "U203522"
    },
    "applicationId": "88888020260903016744",
    "vehicleIdentificationNumber": "WVWZZZ1KZAW123456",
    "licensePlate": "HH-AB 1234",
    "businessTransaction": "AB",
    "status": "bearbeitet",
    "statusTime": "2026-09-03T16:54:41.000+02:00",
    "processingKind": "T",
    "decision": "APPROVED",
    "messages": null,
    "state": "OPEN",
    "order": null,
    "files": [
      {
        "purposeType": "CERTIFICATE",
        "mediaType": "application/pdf",
        "fileAccessKey": "ek_22222222-2222-2222-2222-222222222222_0",
        "expirationTime": "2026-12-08T06:21:26",
        "filename": "Eingang-5_88888020260903016744_Abmeldebescheinigung.pdf"
      }
    ]
  },
  "eventTime": "2026-09-09T06:21:26"
}