Webhooks

HTTPS-Endpunkte für Ereignis-Benachrichtigungen registrieren, Test-Zustellungen auslösen und Signaturen prüfen.

Authentifizierung

Jeder Request braucht einen API-Key im Header. Keys entstehen unter Einstellungen → API (nur Business-Tarif). Details zu Scopes, Idempotenz und Rate-Limits auf der Übersichtsseite.

Authorization: Bearer mxr_live_…

Bleibt in diesem Browser-Tab (sessionStorage), nur für „Ausprobieren“ auf dieser Seite, und geht direkt aus deinem Browser an /api/v1 — kein Versand an unseren Server, kein Log.

Webhook-Endpunkte auflisten

get/api/v1/webhooks

Scope

webhooks:read

curl -X GET "https://maxrechnung.de/api/v1/webhooks" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Liste
  • 401 Kein oder ungültiger API-Key
  • 403 Scope webhooks:read fehlt
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "00000000-0000-0000-0000-000000000000",
      "url": "…",
      "events": [
        "invoice.created"
      ],
      "active": false,
      "created_at": "2026-01-31T12:00:00Z",
      "last_delivery_at": "2026-01-31T12:00:00Z",
      "last_delivery_status": 0
    }
  ]
}

Webhook-Endpunkt registrieren

post/api/v1/webhooks

Antwortet einmalig mit secret (whsec_…) zum Verifizieren der Signatur. Scope webhooks:write.

Scope

webhooks:write

Parameter

  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json · erforderlich

  • url string · uri*https-URL.
  • events "invoice.created" | "invoice.updated" | "invoice.finalized" | "invoice.partially_paid" | "invoice.paid" | "invoice.cancelled" | "invoice.deleted" | "payment.recorded" | "payment.cancelled" | "correction.created" | "invoice.zugferd_ready"[]Default: alle Events. Je Konto höchstens 10 Endpunkte, je Event höchstens 3 (pausierte zählen mit).
{
  "url": "https://example.com/hooks/maxrechnung",
  "events": [
    "invoice.finalized"
  ]
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 201 Angelegt (mit secret)
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope webhooks:write fehlt
  • 409 Idempotency-Key schon mit einem anderen Request verwendet, oder der erste Request damit läuft noch
  • 422 url/events ungültig
  • 429 Rate Limit überschritten

Schema 201

  • object "webhook_endpoint"
  • id string · uuid
  • url string · uri
  • events "invoice.created" | "invoice.updated" | "invoice.finalized" | "invoice.partially_paid" | "invoice.paid" | "invoice.cancelled" | "invoice.deleted" | "payment.recorded" | "payment.cancelled" | "correction.created" | "invoice.zugferd_ready"[]
  • active boolean
  • created_at string · date-time
  • last_delivery_at string · date-time · nullable
  • last_delivery_status integer · nullable
  • secret string

Beispiel 201

{
  "object": "webhook_endpoint",
  "id": "00000000-0000-0000-0000-000000000000",
  "url": "…",
  "events": [
    "invoice.created"
  ],
  "active": false,
  "created_at": "2026-01-31T12:00:00Z",
  "last_delivery_at": "2026-01-31T12:00:00Z",
  "last_delivery_status": 0,
  "secret": "…"
}

Webhook-Endpunkt abrufen

get/api/v1/webhooks/{id}

Scope

webhooks:read

Parameter

  • id path · string · uuid*
curl -X GET "https://maxrechnung.de/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 401 Kein oder ungültiger API-Key
  • 403 Scope webhooks:read fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "webhook_endpoint",
  "id": "00000000-0000-0000-0000-000000000000",
  "url": "…",
  "events": [
    "invoice.created"
  ],
  "active": false,
  "created_at": "2026-01-31T12:00:00Z",
  "last_delivery_at": "2026-01-31T12:00:00Z",
  "last_delivery_status": 0
}

Webhook-Endpunkt löschen

delete/api/v1/webhooks/{id}

Scope

webhooks:write

Parameter

  • id path · string · uuid*
curl -X DELETE "https://maxrechnung.de/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Gelöscht
  • 401 Kein oder ungültiger API-Key
  • 403 Scope webhooks:write fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object "webhook_endpoint"
  • id string · uuid
  • deleted true

Beispiel 200

{
  "object": "webhook_endpoint",
  "id": "00000000-0000-0000-0000-000000000000",
  "deleted": true
}

Test-Zustellung senden

post/api/v1/webhooks/{id}/test

Schickt sofort (nicht über die Queue) einen signierten POST mit type:"webhook.test" und gültigem X-Webhook-Signature-Header an den Endpunkt — zum Verifizieren der Signaturprüfung. Rührt die last_delivery_*-Statistik nicht an. Antwort: { object:"webhook_test", endpoint_id, delivered, status | error } (immer 200, auch wenn der Endpunkt nicht erreichbar war). Scope webhooks:write.

Scope

webhooks:write

Parameter

  • id path · string · uuid*
curl -X POST "https://maxrechnung.de/api/v1/webhooks/{id}/test" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Test ausgeführt
  • 401 Kein oder ungültiger API-Key
  • 403 Scope webhooks:write fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object "webhook_test"
  • endpoint_id string · uuid
  • delivered boolean
  • status integerHTTP-Status des Endpunkts (wenn delivered)
  • error stringVerbindungsfehler (wenn nicht delivered)

Beispiel 200

{
  "object": "webhook_test",
  "endpoint_id": "00000000-0000-0000-0000-000000000000",
  "delivered": false,
  "status": 0,
  "error": "…"
}

Empfangene Signatur prüfen

post/api/v1/webhooks/{id}/verify

Prüft eine empfangene Zustellung: Request-Body = der exakte rohe Payload. Mit Header X-Webhook-Signature-V2 (t=<unix>,v1=<hex>) wird zeitgebunden geprüft (scheme: "v2", ?tolerance= Sekunden, Vorgabe 300; reason = malformed | expired | mismatch), sonst klassisch über X-Webhook-Signature (mit oder ohne sha256=-Präfix) oder ?signature= (scheme: "v1"). Vergleich konstantzeitig gegen das Secret des Endpunkts. Kein Seiteneffekt. Scope webhooks:read. So verifiziert man auch selbst: V2 HMAC_SHA256(t + "." + rawBody, secret) als Hex gegen v1, dazu t im Fenster; klassisch HMAC_SHA256(rawBody, secret) als Hex mit sha256=-Präfix.

Scope

webhooks:read

Parameter

  • id path · string · uuid*
  • signature query · stringAlternative zum Header X-Webhook-Signature.
  • tolerance query · integerReplay-Fenster in Sekunden für X-Webhook-Signature-V2 (Abstand von t zum Jetzt).

Request-Body · application/json · erforderlich

string

"…"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Ergebnis
  • 400 Signatur fehlt
  • 401 Kein oder ungültiger API-Key
  • 403 Scope webhooks:read fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object "webhook_signature"
  • endpoint_id string · uuid
  • valid boolean
  • scheme "v1" | "v2"Welche Signatur geprüft wurde.
  • timestamp integert aus der V2-Signatur (Unix-Sekunden), falls lesbar.
  • reason "malformed" | "expired" | "mismatch"Nur bei valid: false und V2.

Beispiel 200

{
  "object": "webhook_signature",
  "endpoint_id": "00000000-0000-0000-0000-000000000000",
  "valid": false,
  "scheme": "v1",
  "timestamp": 0,
  "reason": "malformed"
}

Schemas

Von den Endpunkten oben referenzierte Objekte. Vollständig auch in der OpenAPI-Spezifikation.