Webhooks

Jeder Zustandswechsel eines Vorgangs kommt als signierter POST an einen Endpunkt, den Sie betreiben. Der Vertrag ist Webhooks 3.1.0 — derselbe wie bei kennzeichen.dev; ein bestehender Empfänger passt unverändert.

Einrichtung im Dashboard

Unter Webhooks legen Sie je Instanz einen oder mehrere Webhooks an. Das geht nur im Dashboard — eine Schnittstelle zum Anlegen, Ändern oder Testen von Webhooks gibt es nicht:

Eigene Kopfzeilen lassen sich nicht einstellen; zusätzliche Absicherung erreichen Sie über eine schwer erratbare URL. Eine Änderung von URL oder Secret gilt nur für neue Ereignisse — Wiederholungen laufen mit dem Stand, den das Ereignis bei seiner Entstehung hatte. Wechseln Sie ein Secret deshalb über einen zweiten Webhook, den Sie parallel betreiben, bis für den alten nichts mehr aussteht.

PING lösen Sie im Dashboard von Hand aus. So prüfen Sie Erreichbarkeit und Signaturprüfung, bevor fachliche Ereignisse anfallen:

{ "eventType": "PING", "eventTime": "2026-09-15T09:15:30" }

Ereignistypen

Ein Webhook erhält nur, was er abonniert hat. Jeder Typ ist einzeln abonnierbar. Ausnahme ist der PING von Hand: Er geht an den gewählten Webhook, auch wenn dieser PING nicht abonniert hat.

WG und WZ, NZ und TZ teilen sich den Typ — unterscheiden Sie sie über businessTransaction. Das gilt auch für Anträge, die nicht über Ihre Schnittstelle, sondern im Dashboard gestellt wurden.

Die übrigen Typen des Vertrags (DELIVERY_*, LICENSE_PLATE_RESERVATION_*) erzeugt diese Schnittstelle nicht.

FEE_NOTICE_XKFZ_EVENT trägt den Bescheid, wie ihn GET /vehicleDeregistrations/feeNotices liefert. Ab mehr als 500 Anträgen teilt die Behörde einen Bescheid auf mehrere Nachrichten; nur die letzte nennt Gesamtbetrag, Bankverbindung, Kassenzeichen und PDF. Ein solcher Bescheid kommt deshalb einmal, mit seiner abschließenden Nachricht (der mit Gesamtbetrag): part ist dann etwa { "number": 2, "of": 2 } — die Zählung laut Bescheidkopf, die auch eigenständige Bescheide eines Zeitraums mitzählen kann —, amount die Summe sämtlicher Anträge und applications enthält die Anträge aller bis dahin eingegangenen Teile. Frühere Teile erzeugen kein eigenes Ereignis und keinen Listeneintrag. Trifft ein früherer Teil erst nach dem letzten ein, kommt das Ereignis erneut — mit derselben id, derselben messageId und demselben amount, nur mit ergänzten applications. Zahlen Sie je messageId einmal. applications[].contractPartner nennt den Vertragspartner (Referenztyp 28), wenn die Behörde ihn angibt; weicht er vom Vertragspartner des eigenen Antrags ab, steht der Antrag auf MISMATCH und seine Gebühr wird dem Vorgang nicht zugeschrieben.

Wann ein Ereignis entsteht

Das erste Ereignis eines Antrags entsteht nach dem Versand — sobald die Quittung des KBA vorliegt oder der Versand gescheitert ist, nicht schon beim POST. Ein erkannter Wiederholungsversuch (siehe Doppelantragsschutz) sendet nichts erneut an das KBA. Läuft der Versand des ersten Antrags noch, löst er auch kein Ereignis aus; das Ergebnis meldet das Ereignis des ersten Antrags. Ist der erste Antrag schon quittiert, meldet die Wiederholung dessen Stand in einem weiteren Ereignis erneut — mit demselben status und denselben messages wie zuvor, vollständig aus dem Speicher.

Weitere Ereignisse folgen mit dem Bescheid, wenn eine Statusabfrage beim KBA einen neuen Zustand ergibt (etwa FORWARDED), wenn das KBA eine Begründung nachreicht und wenn nach dem Endzustand noch Belege eintreffen. Portal und Fachverfahren schicken ihre Bescheide unter Umständen Tage auseinander. Solche Ereignisse können denselben status tragen wie das vorige. Werten Sie files und messages deshalb auch nach einem Endzustand aus.

Bricht die Instanz zwischen Antwort und Versand ab, meldet sie beim nächsten Start die Vorgänge als FAILED mit Code 99995 und retryable: true, die zu diesem Zeitpunkt schon länger als 15 Minuten angelegt und nie gesendet sind. Einen regelmäßigen Lauf gibt es nicht: Ein Vorgang, der beim Neustart jünger war, bleibt ohne Ereignis auf angelegt, bis die Instanz erneut startet. Fragen Sie deshalb Aufträge mit GET …/orders?state=angelegt ab, und melden Sie einen, der länger als 15 Minuten ohne applicationId so steht, beim Support.

Rumpf

Alle Vorgangsereignisse haben denselben Rumpf:

Felder ohne Wert fehlen im Rumpf. Die Belege holen Sie mit dem fileAccessKey ab — siehe Belege abrufen.

Ein vorübergehend gescheiterter Antrag:

{
  "eventType": "VEHICLE_TRANSFER_XKFZ_EVENT",
  "order": { "id": 42, "externalId": "umschreibung-4711" },
  "attemptOf": 42,
  "attempt": 1,
  "businessTransaction": "UG",
  "status": "FAILED",
  "derivedStatus": "FAILURE",
  "applicationId": "88888020260915000042",
  "licensePlate": "SL-OA 1417",
  "messages": [
    { "type": "QUITTUNG", "kind": "Fehler", "code": "07082", "text": "Das i-Kfz Portal steht aktuell nicht zur Verfügung." }
  ],
  "retryable": true,
  "eventTime": "2026-09-15T10:05:00"
}

retryable ist ein Hinweis, keine Zusage: Ob der Antrag beim KBA angekommen ist, sagt eine Fehlerquittung nicht sicher. Wer selbsttätig erneut sendet, riskiert eine doppelte Zulassung.

derivedStatus

INPUT_INVALID steht im Vertrag, wird von dieser Schnittstelle derzeit nicht gesendet. Bei HA und den Zulassungsvorgängen kommt eine Schemaprüfung des KBA als FAILURE; der Grund steht in messages[].additional.

Signatur prüfen

Jede Zustellung trägt diese Kopfzeilen:

Rechnen Sie die Signatur über die unveränderten Bytes des Rumpfs, nicht über ein geparstes und neu serialisiertes Objekt: Schon eine andere Reihenfolge der Felder oder ein anderes Escaping ergibt eine andere Signatur. Vergleichen Sie zeitkonstant.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

/** Prüft X-Signature: HMAC-SHA256 über den Rohtext, hexadezimal. */
export function signaturIstGueltig(rohtext, signatur, secret) {
  const erwartet = Buffer.from(createHmac('sha256', secret).update(rohtext).digest('hex'), 'utf8');
  const erhalten = Buffer.from(String(signatur ?? ''), 'utf8');
  return erwartet.length === erhalten.length && timingSafeEqual(erwartet, erhalten);
}

Ein vollständiger Empfänger ohne weitere Abhängigkeiten:

import { createServer } from 'node:http';
import { signaturIstGueltig } from './signatur.mjs';

const SECRET = process.env.WEBHOOK_SECRET ?? '';
// In Ihrem System: eine Tabelle mit eindeutigem Schlüssel auf der Ereignis-Id.
const bekannteEreignisse = new Set();

createServer((anfrage, antwort) => {
  const teile = [];
  anfrage.on('data', (teil) => teile.push(teil));
  anfrage.on('end', () => {
    const rohtext = Buffer.concat(teile);
    if (!signaturIstGueltig(rohtext, anfrage.headers['x-signature'], SECRET)) {
      antwort.writeHead(401).end();
      return;
    }
    const eventId = String(anfrage.headers['x-event-id'] ?? '');
    if (!bekannteEreignisse.has(eventId)) {
      bekannteEreignisse.add(eventId);
      const ereignis = JSON.parse(rohtext.toString('utf8'));
      console.log(ereignis.eventType, ereignis.order?.id, ereignis.status);
    }
    antwort.writeHead(202).end();
  });
}).listen(Number(process.env.PORT ?? 8080));

PHP

<?php
/** Prüft X-Signature: HMAC-SHA256 über den Rohtext, hexadezimal. */
function signaturIstGueltig(string $rohtext, string $signatur, string $secret): bool
{
    return hash_equals(hash_hmac('sha256', $rohtext, $secret), $signatur);
}

<?php
require __DIR__ . '/signatur.php';

$rohtext = file_get_contents('php://input');
$signatur = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
if (!signaturIstGueltig($rohtext, $signatur, (string) getenv('WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}

$eventId = $_SERVER['HTTP_X_EVENT_ID'] ?? '';
$ereignis = json_decode($rohtext, true);
// Idempotent speichern, etwa: INSERT … ON CONFLICT (event_id) DO NOTHING
error_log(sprintf('%s %s %s', $eventId, $ereignis['eventType'] ?? '', $ereignis['status'] ?? ''));

http_response_code(202);

Zustellung und Wiederholung

Antwortet Ihr Endpunkt nicht mit einem 2xx — oder gar nicht —, wird wiederholt. Erwartet ist 202, jeder andere Erfolgscode gilt ebenso.

• Je Versuch gilt ein Zeitlimit von 15 Sekunden.
• Weiterleitungen (3xx) werden nicht verfolgt und zählen als Fehlschlag.
• Nach dem siebten Versuch — rund 31 Stunden nach dem Ereignis — gibt die Zustellung auf. Im Dashboard unter „Webhooks" lässt sie sich erneut anstoßen; von selbst kommt sie nicht mehr. Fragen Sie spätestens dann den Stand über die Vorgangsauskunft ab.

Idempotenz

Die Zustellung folgt „at-least-once": Dasselbe Ereignis kann mehrfach ankommen, und die Reihenfolge ist nicht garantiert.

• X-Event-Id ist bei allen Versuchen desselben Ereignisses gleich — der Schlüssel zum Entdoppeln. Im Rumpf steht sie bewusst nicht, damit der Rumpf dem Vertrag entspricht.
• Der Rumpf ist bei jedem Versuch bitgleich; auch sein Hash taugt als Schlüssel.
• Zwei Ereignisse zum selben Vorgang bringen Sie über eventTime in Reihenfolge. Bei gleicher eventTime ist die Reihenfolge offen. Den aktuellen Stand nennt im Zweifel die Vorgangsauskunft.
• Bestätigen Sie schnell: Ereignis speichern, 202 antworten, dann verarbeiten. Wer erst verarbeitet, läuft in das Zeitlimit und erzeugt unnötige Wiederholungen.