Pro-Feature

Webhooks

Erhalte Echtzeit-Benachrichtigungen, wenn in time2invoice etwas passiert. Webhooks senden HTTP-POST-Requests an deine URL, sobald eine Rechnung erstellt, bezahlt oder ein Kunde angelegt wird.

Webhook einrichten

Gehe zu Einstellungen → API-Zugang → Webhooksund klicke auf "Neuen Webhook erstellen". Du gibst an:

Endpoint-URL

Die HTTPS-URL, an die Events gesendet werden (z.B. https://dein-server.de/webhook)

Events

Welche Events dich interessieren (z.B. nur Zahlungseingaenge)

Secret

Wird automatisch generiert. Damit verifizierst du die Signatur jedes Requests.

Verfuegbare Events

Event	Beschreibung	Ausloeser
invoice.created	Neue Rechnung erstellt	Rechnung als Draft angelegt
invoice.sent	Rechnung versendet	Status wechselt zu "sent"
invoice.paid	Zahlung eingegangen	Status wechselt zu "paid"
invoice.reminder_sent	Mahnung versendet	Zahlungserinnerung/Mahnung per E-Mail verschickt
customer.created	Neuer Kunde angelegt	Kunde wird erstellt
expense.created	Neue Ausgabe erfasst	Ausgabe wird erstellt

Payload-Format

Jeder Webhook-Request ist ein POST mit JSON-Body und speziellen Headern:

Webhook Request

POST https://dein-server.de/webhook
Content-Type: application/json
X-T2I-Event: invoice.created
X-T2I-Signature: a1b2c3d4e5f6...

{
  "event": "invoice.created",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "data": {
    "id": "jd7x...",
    "invoiceNumber": "FR-2026-003",
    "netAmount": 1800,
    "customerId": "k3f9..."
  }
}

Beispiel: `invoice.paid`

Beim Zahlungseingang enthaelt data vollen Kundenbezug (inkl. customerSevdeskId fuer externen SID-Sync). Geldbetraege sind EUR-Werte (Buchhaltungswaehrung); currency ist die originale Belegwaehrung.

invoice.paid — data

{
  "invoiceId": "jd7x...",
  "invoiceNumber": "FR-2026-003",
  "paidAt": 1735689600000,
  "paidAmount": 2142,
  "customerId": "k3f9...",
  "customerName": "Acme GmbH",
  "customerSevdeskId": "12345",
  "netAmount": 1800,
  "grossAmount": 2142,
  "amountCurrency": "EUR",
  "currency": "EUR"
}

Header

Header	Beschreibung
Content-Type	Immer `application/json`
X-T2I-Event	Name des Events (z.B. `invoice.paid`)
X-T2I-Signature	HMAC-SHA256 Signatur des Request-Bodys

Signatur verifizieren

Jeder Request enthaelt eine HMAC-SHA256-Signatur im X-T2I-Signature-Header. Verifiziere diese immer, um sicherzustellen, dass der Request wirklich von time2invoice stammt.

Node.js -- Signatur verifizieren

import crypto from "crypto";

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body, "utf-8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

// Express-Beispiel:
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-t2i-signature"];
  const isValid = verifyWebhookSignature(
    req.body.toString(),
    signature,
    "whsec_deinSecret..."
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = JSON.parse(req.body);
  console.log("Event:", event, data);
  res.status(200).send("OK");
});

Wichtig: Signatur immer pruefen!

Ohne Signaturpruefung koennten Dritte gefaelschte Requests an deine URL senden. Nutze immer timingSafeEqual statt einfachem String-Vergleich.

Best Practices

Schnell antworten

Antworte innerhalb von 5 Sekunden mit Status 200. Verarbeitung asynchron ausfuehren.

Idempotent verarbeiten

Events koennen im Fehlerfall mehrfach gesendet werden. Pruefe die Event-ID vor der Verarbeitung.

HTTPS verwenden

Nutze immer eine HTTPS-URL fuer deinen Webhook-Endpoint.

Zustellung & Wiederholungen

Jede Zustellung wird protokolliert. Antwortet dein Endpoint nicht mit einem 2xx-Status (oder ist er nicht erreichbar), wird die Zustellung mit exponentiellem Backoff bis zu 5 Mal wiederholt (ca. 1 min, 2 min, 4 min, 8 min, gedeckelt bei 2 h). Payload und Signatur bleiben ueber alle Versuche identisch — verarbeite Events daher idempotent. Netzwerkfehler und Nicht-2xx-Antworten gelten als Fehlversuch und werden erneut zugestellt.

Den aktuellen Zustellstatus je Endpoint siehst du unter Einstellungen → Integrationen.

Pro-Feature

Webhooks sind im Pro-Plan (12 EUR/Monat) enthalten. Fuer die vollstaendige API-Referenz siehe die REST API-Dokumentation.