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 → Webhooks und 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"
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..."
  }
}

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.

Pro-Feature

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