Webhooks
Signierte Benachrichtigungen zu Bestellungen, Tickets, Check-ins und Erstattungen erhalten
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
| Ereignis | Wann es gesendet wird | data |
|---|---|---|
order.paid | Eine Bestellung ist bezahlt | orderId, eventId, totalCents, currency, tickets, paidAt |
order.refunded | Eine Bestellung ist vollständig erstattet | orderId, totalCents |
ticket.issued | Tickets für eine Bestellung sind ausgestellt | orderId, eventId, ticketIds |
ticket.transferred | Ein Ticket wurde weitergegeben und die neue Inhaberin oder der neue Inhaber hat es angenommen | transferId, eventId, ticketId, previousTicketId |
ticket.checked_in | Ein Ticket ist am Einlass eingecheckt | ticketId, eventId, doorId, admissions, checkedInAt |
webhook.test | Sie klicken auf Test senden | leer |
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
https://-URL auf Port 443 mit öffentlichem Hostnamen ein. Adressen in privaten Netzen werden abgelehnt, Weiterleitungen nicht verfolgt.whsec_…). Es wird nur einmal angezeigt.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.
| Anfrage | Endpunktgruppe |
|---|---|
GET /api/partner/projects/{projectId}/webhooks listet die Endpunkte, die dieser Schlüssel abonniert hat | webhooks.read |
POST /api/partner/projects/{projectId}/webhooks abonniert einen: {"url", "description", "eventTypes"} | webhooks.manage |
DELETE /api/partner/projects/{projectId}/webhooks/{webhookId} kündigt einen | webhooks.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 Gruppeorders.readdes Schlüssels,ticket.*-Ereignissetickets.read, jeweils auch für das Projekt eingeschaltet, und jedes Ereignis brauchtwebhooks.manage. Schalten Sie eine dieser Gruppen aus, erhalten die Endpunkte des Schlüssels diese Ereignisse nicht mehr; eine bereits wartende Zustellung schlägt mitendpoint_disabledfehl 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 "", 204Der 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(deridim 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:
| Zelle | IPv4 | IPv6 |
|---|---|---|
Beta (beta-rest-api.tixfin.com) | 152.53.254.3 | keine: 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.