TixFinDocs

Webhooks

Receive signed notifications for orders, tickets, check-ins and refunds

7 min read

TixFin sends an HTTPS POST to your server when an order is paid, tickets are issued or passed on, a ticket is checked in, or an order is refunded. Each request is signed with a secret only you and TixFin hold.

Where: account menu (avatar) → Account → Webhooks Who can do this: members allowed to update the project (owners, admins, or a role with project update). You need two-factor authentication; adding, changing, rotating and deleting an endpoint ask you to confirm your second factor again if you last did so more than ten minutes ago.

Events

EventWhen it is sentdata
order.paidAn order is paidorderId, eventId, totalCents, currency, tickets, paidAt
order.refundedAn order is refunded in fullorderId, totalCents
ticket.issuedTickets are issued for an orderorderId, eventId, ticketIds
ticket.transferredA ticket is passed on and the new holder accepts ittransferId, eventId, ticketId, previousTicketId
ticket.checked_inA ticket is checked in at the doorticketId, eventId, doorId, admissions, checkedInAt
webhook.testYou press Send testempty

No personal data. A payload carries IDs, amounts and times only — never a name, an email address, a phone number or anything a person typed. To read more about an order or ticket, call the partner API with a key that has the matching endpoint group (orders.read, tickets.read).

Set up an endpoint

Open Account → Webhooks and click Add endpoint.
Enter an https:// URL on port 443 with a public host name. Addresses on private networks are refused, and redirects are not followed.
Choose the events to receive.
Copy the signing secret (whsec_…). It is shown once.
Click Send test and check the delivery log.

A project can have up to 10 endpoints.

Subscribe with a partner API key

Integrations such as Zapier, Make and n8n subscribe and unsubscribe through the partner API with a key, instead of an endpoint someone adds by hand. The requests and the deliveries are the same as above.

RequestEndpoint group
GET /api/partner/projects/{projectId}/webhooks lists the endpoints this key subscribedwebhooks.read
POST /api/partner/projects/{projectId}/webhooks subscribes one: {"url", "description", "eventTypes"}webhooks.manage
DELETE /api/partner/projects/{projectId}/webhooks/{webhookId} unsubscribes onewebhooks.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"]}'

The answer carries the endpoint and its signing secret (whsec_…), shown once.

  • A key hears only what it can read. order.* events need the key's orders.read group and ticket.* events its tickets.read, each also enabled for the project, and every event needs webhooks.manage. When you switch one of those groups off, the key's endpoints stop receiving those events; a delivery already waiting fails with endpoint_disabled and is not sent.
  • Revoking the key deletes its endpoints, and an expired key's endpoints are deleted within the hour. Each deletion appears in the change history, where the API names the key in apiKeyId.
  • Each key has its own 10 endpoints, apart from the project's 10, so an integration cannot use up the endpoints you add yourself.
  • A key sees and deletes only its own endpoints. Account → Webhooks shows them beside yours, and you can switch off or delete any of them there.

The request

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"
  }
}

Requests follow the Standard Webhooks specification, so its libraries verify them too.

Verify the signature

The signature is an HMAC-SHA256 over webhook-id, webhook-timestamp and the raw body joined by dots, keyed with the secret's bytes after whsec_ (base64-decoded). Verify before parsing the JSON, compare in constant time, and refuse a timestamp more than five minutes away from your clock.

// 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);
  // Queue the event and answer quickly; deduplicate on event.id.
  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

The header may carry more than one signature, separated by spaces. Accept the request if any v1 signature matches.

Delivery and retries

  • Answer with a 2xx status within 10 seconds. Anything else — another status, a timeout, a redirect, a TLS error — counts as a failure.
  • Retries: after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours: eight attempts over about two days. Then the delivery is marked failed; you can redeliver it from the log.
  • At least once. The same event can arrive more than once, and events can arrive out of order. Deduplicate on webhook-id (the body's id), which stays the same across retries and redeliveries.
  • Endpoints that keep failing are switched off. If every attempt to an endpoint fails for five days, or more than 10,000 deliveries are waiting, TixFin disables the endpoint and stops its pending deliveries. Switch it back on in Account → Webhooks once it works.

Delivery log

Account → Webhooks shows each endpoint's deliveries from the last 30 days: the request body as sent, and every attempt with its status code or error and how long it took. TixFin does not keep your server's response body.

Change history

Account → Webhooks also shows who added, changed, rotated the secret of, deleted or automatically disabled an endpoint, and when, newest first: by you, by a team member, by TixFin support, or automatically with the reason. It never shows a secret. The same history is GET /projects/{projectId}/partner-api/webhooks/audit, 50 entries per page; pass a page's nextCursor as cursor for the next one.

Rotate the secret

Click Rotate secret. You get a new secret at once. For 24 hours every request carries two signatures — one with the new secret and one with the old — so you can update your server without missing a delivery.

Security

  • TixFin only connects to public addresses on port 443 and checks the address on every connection, so a host name that later resolves to a private network is refused.
  • Keep the secret in your server's secret store; never in client-side code.
  • A deleted endpoint's secret is destroyed with it.

Sender addresses

Webhooks reach your endpoint from one fixed address per TixFin cell. If your firewall allow-lists callers, admit:

CellIPv4IPv6
Beta (beta-rest-api.tixfin.com)152.53.254.3none: deliveries use IPv4 only

The signature stays the authentication: an allow-list is an extra, never a replacement. A change of address is announced on this page before it takes effect.

On this page