TixFinDocs
API-Integration

Webhooks

Signierte Benachrichtigungen zu Bestellungen, Tickets, Check-ins und Erstattungen erhalten

7 Min. Lesezeit

TixFin sendet einen HTTPS-POST an Ihren Server, wenn eine Bestellung bezahlt ist, Tickets ausgestellt oder weitergegeben werden, ein Ticket eingecheckt oder eine Bestellung erstattet ist. Jede Anfrage ist mit einem Geheimnis signiert, das nur Sie und TixFin kennen.

Wo: Kontomenü (Avatar) → Konto → Webhooks Wer kann das: Mitglieder, die das Projekt bearbeiten dürfen (Inhaber, Admins oder eine Rolle mit Projektbearbeitung). Sie brauchen Zwei-Faktor-Authentifizierung; beim Hinzufügen, Ändern, Erneuern und Löschen eines Endpunkts bestätigen Sie Ihren zweiten Faktor erneut, wenn das letzte Mal mehr als zehn Minuten her ist.

Ereignisse

EreignisWann es gesendet wirddata
order.paidEine Bestellung ist bezahltorderId, eventId, totalCents, currency, tickets, paidAt
order.refundedEine Bestellung ist vollständig erstattetorderId, totalCents
ticket.issuedTickets für eine Bestellung sind ausgestelltorderId, eventId, ticketIds
ticket.transferredEin Ticket wurde weitergegeben und die neue Inhaberin oder der neue Inhaber hat es angenommentransferId, eventId, ticketId, previousTicketId
ticket.checked_inEin Ticket ist am Einlass eingechecktticketId, eventId, doorId, admissions, checkedInAt
webhook.testSie klicken auf Test sendenleer

Keine personenbezogenen Daten. Der Inhalt enthält nur IDs, Beträge und Zeitpunkte — nie einen Namen, eine E-Mail-Adresse, eine Telefonnummer oder etwas, das eine Person eingegeben hat. Mehr zu einer Bestellung oder einem Ticket lesen Sie über die Partner-API mit einem Schlüssel der passenden Endpunktgruppe (orders.read, tickets.read).

Einen Endpunkt einrichten

Öffnen Sie Konto → Webhooks und klicken Sie auf Endpunkt hinzufügen.
Geben Sie eine https://-URL auf Port 443 mit öffentlichem Hostnamen ein. Adressen in privaten Netzen werden abgelehnt, Weiterleitungen nicht verfolgt.
Wählen Sie die Ereignisse.
Kopieren Sie das Signatur-Geheimnis (whsec_…). Es wird nur einmal angezeigt.
Klicken Sie auf Test senden und prüfen Sie das Zustellprotokoll.

Ein Projekt kann bis zu 10 Endpunkte haben.

Mit einem Partner-API-Schlüssel abonnieren

Integrationen wie Zapier, Make und n8n abonnieren und kündigen über die Partner-API mit einem Schlüssel, statt dass jemand einen Endpunkt von Hand anlegt. Anfragen und Zustellungen sind dieselben wie oben.

AnfrageEndpunktgruppe
GET /api/partner/projects/{projectId}/webhooks listet die Endpunkte, die dieser Schlüssel abonniert hatwebhooks.read
POST /api/partner/projects/{projectId}/webhooks abonniert einen: {"url", "description", "eventTypes"}webhooks.manage
DELETE /api/partner/projects/{projectId}/webhooks/{webhookId} kündigt einenwebhooks.manage
curl -X POST "https://beta-rest-api.tixfin.com/api/partner/projects/$TIXFIN_PROJECT_ID/webhooks" \
  -H "X-API-Key: $TIXFIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/tixfin", "eventTypes": ["order.paid"]}'

Die Antwort enthält den Endpunkt und sein Signatur-Geheimnis (whsec_…), das nur einmal angezeigt wird.

  • Ein Schlüssel hört nur, was er lesen darf. order.*-Ereignisse brauchen die Gruppe orders.read des Schlüssels, ticket.*-Ereignisse tickets.read, jeweils auch für das Projekt eingeschaltet, und jedes Ereignis braucht webhooks.manage. Schalten Sie eine dieser Gruppen aus, erhalten die Endpunkte des Schlüssels diese Ereignisse nicht mehr; eine bereits wartende Zustellung schlägt mit endpoint_disabled fehl und wird nicht gesendet.
  • Ein widerrufener Schlüssel verliert seine Endpunkte sofort, die eines abgelaufenen werden innerhalb einer Stunde gelöscht. Jede Löschung steht im Änderungsverlauf; die API nennt den Schlüssel in apiKeyId.
  • Jeder Schlüssel hat eigene 10 Endpunkte, getrennt von den 10 des Projekts, damit eine Integration die Endpunkte, die Sie selbst anlegen, nicht aufbraucht.
  • Ein Schlüssel sieht und löscht nur seine eigenen Endpunkte. Konto → Webhooks zeigt sie neben Ihren, und Sie können jeden davon dort ausschalten oder löschen.

Die Anfrage

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: TixFin-Webhooks/1
webhook-id: 4b8b8f4e-2c1e-4d47-9a51-0d2f7a1c9e10
webhook-timestamp: 1793534400
webhook-signature: v1,<base64 HMAC-SHA256>

{
  "id": "4b8b8f4e-2c1e-4d47-9a51-0d2f7a1c9e10",
  "type": "order.paid",
  "createdAt": "2026-11-01T10:00:00Z",
  "projectId": "3f0b3c2e-5a1d-4b3e-9f61-2b7a3c1d4e5f",
  "data": {
    "orderId": "0199a0c4-2222-7000-8000-000000000001",
    "eventId": "0199a0c4-3333-7000-8000-000000000002",
    "totalCents": 4800,
    "currency": "EUR",
    "tickets": 2,
    "paidAt": "2026-11-01T10:00:00Z"
  }
}

Die Anfragen folgen der Spezifikation Standard Webhooks; deren Bibliotheken prüfen sie ebenfalls.

Die Signatur prüfen

Die Signatur ist ein HMAC-SHA256 über webhook-id, webhook-timestamp und den unveränderten Body, mit Punkten verbunden, geschlüsselt mit den Bytes des Geheimnisses nach whsec_ (Base64-dekodiert). Prüfen Sie vor dem Parsen des JSON, vergleichen Sie in konstanter Zeit und lehnen Sie einen Zeitstempel ab, der mehr als fünf Minuten von Ihrer Uhr abweicht.

// Node.js 18+ with Express
const crypto = require('node:crypto');
const express = require('express');

const secret = Buffer.from(process.env.TIXFIN_WEBHOOK_SECRET.replace(/^whsec_/, ''), 'base64');

function verify(id, timestamp, body, header) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${id}.${timestamp}.`).update(body).digest();
  return header.split(' ').some((part) => {
    const [version, signature] = part.split(',');
    const given = Buffer.from(signature ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

const app = express();
app.post('/webhooks/tixfin', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verify(req.get('webhook-id'), req.get('webhook-timestamp'), req.body, req.get('webhook-signature') ?? '');
  if (!ok) return res.status(401).end();
  const event = JSON.parse(req.body);
  // Ereignis einreihen und schnell antworten; Doppelte an event.id erkennen.
  res.status(204).end();
});
# Python 3 with Flask
import base64, hashlib, hmac, os, time
from flask import Flask, request, abort

secret = base64.b64decode(os.environ["TIXFIN_WEBHOOK_SECRET"].removeprefix("whsec_"))
app = Flask(__name__)

@app.post("/webhooks/tixfin")
def tixfin():
    msg_id = request.headers["webhook-id"]
    ts = request.headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        abort(401)
    expected = base64.b64encode(
        hmac.new(secret, f"{msg_id}.{ts}.".encode() + request.get_data(), hashlib.sha256).digest()
    ).decode()
    given = [p.split(",", 1)[1] for p in request.headers["webhook-signature"].split() if p.startswith("v1,")]
    if not any(hmac.compare_digest(expected, g) for g in given):
        abort(401)
    return "", 204

Der Header kann mehrere Signaturen enthalten, durch Leerzeichen getrennt. Nehmen Sie die Anfrage an, wenn eine v1-Signatur passt.

Zustellung und Wiederholungen

  • Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status. Alles andere — ein anderer Status, eine Zeitüberschreitung, eine Weiterleitung, ein TLS-Fehler — gilt als Fehlschlag.
  • Wiederholungen: nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden, 12 Stunden und 24 Stunden: acht Versuche über etwa zwei Tage. Danach gilt die Zustellung als fehlgeschlagen; Sie können sie im Protokoll erneut zustellen.
  • Mindestens einmal. Dasselbe Ereignis kann mehrfach ankommen, und Ereignisse können in anderer Reihenfolge ankommen. Erkennen Sie Doppelte an webhook-id (der id im Body), die bei Wiederholungen gleich bleibt.
  • Dauerhaft fehlerhafte Endpunkte werden abgeschaltet. Schlägt fünf Tage lang jeder Versuch fehl oder warten mehr als 10.000 Zustellungen, deaktiviert TixFin den Endpunkt und stoppt seine ausstehenden Zustellungen. Schalten Sie ihn unter Konto → Webhooks wieder ein, sobald er funktioniert.

Zustellprotokoll

Konto → Webhooks zeigt die Zustellungen jedes Endpunkts der letzten 30 Tage: den gesendeten Body und jeden Versuch mit Statuscode oder Fehler und Dauer. Den Antwort-Body Ihres Servers speichert TixFin nicht.

Änderungsverlauf

Konto → Webhooks zeigt auch, wer einen Endpunkt hinzugefügt, geändert, sein Geheimnis erneuert, gelöscht oder automatisch deaktiviert hat, und wann, neueste zuerst: von Ihnen, von einem Teammitglied, vom TixFin-Support oder automatisch mit dem Grund. Ein Geheimnis zeigt er nie. Derselbe Verlauf ist GET /projects/{projectId}/partner-api/webhooks/audit, 50 Einträge pro Seite; übergeben Sie den nextCursor einer Seite als cursor für die nächste.

Das Geheimnis erneuern

Klicken Sie auf Geheimnis erneuern. Sie erhalten sofort ein neues Geheimnis. 24 Stunden lang trägt jede Anfrage zwei Signaturen — eine mit dem neuen und eine mit dem alten Geheimnis —, damit Sie Ihren Server ohne verpasste Zustellung umstellen können.

Sicherheit

  • TixFin verbindet sich nur mit öffentlichen Adressen auf Port 443 und prüft die Adresse bei jeder Verbindung; ein Hostname, der später auf ein privates Netz zeigt, wird abgelehnt.
  • Bewahren Sie das Geheimnis im Geheimnisspeicher Ihres Servers auf, nie im Client-Code.
  • Das Geheimnis eines gelöschten Endpunkts wird mit ihm vernichtet.

Absenderadressen

Webhooks erreichen Ihren Endpunkt von einer festen Adresse je TixFin-Zelle. Wenn Ihre Firewall Absender freischaltet, lassen Sie diese zu:

ZelleIPv4IPv6
Beta (beta-rest-api.tixfin.com)152.53.254.3keine: Zustellungen nutzen nur IPv4

Die Signatur bleibt die Authentifizierung: Eine Freigabeliste ergänzt sie, ersetzt sie nie. Eine geänderte Adresse kündigen wir auf dieser Seite an, bevor sie gilt.

Verwandte Seiten

Auf dieser Seite