Webhooks

Partner-facing webhooks are on the roadmap and not available yet — the Partner API currently only supports the read endpoints described in the API Overview (events, ticket catalog, tickets, orders). The event types and payloads below describe the planned design.

Get notified instantly when events happen in TIXFIN.

What Are Webhooks?

Webhooks send HTTP POST requests to your server when specific events occur (like a ticket purchase).

Use Cases:

Send custom confirmation emails
Update your CRM
Sync with accounting software
Trigger custom workflows
Real-time inventory management

Available Events

Event	When It Fires
`ticket.purchased`	Ticket bought
`ticket.checked_in`	Ticket scanned at entry
`ticket.refunded`	Refund processed
`ticket.transferred`	Ticket transferred to someone else

Event	When It Fires
`event.created`	New event created
`event.published`	Event goes live
`event.cancelled`	Event cancelled
`event.updated`	Event details changed

Event	When It Fires
`payment.succeeded`	Payment completed
`payment.failed`	Payment failed
`refund.created`	Refund initiated
`payout.paid`	Payout sent to your account

Setup

1. Create Endpoint

Create an HTTPS endpoint on your server:

// Node.js/Express example
app.post('/webhooks/tixfin', (req, res) => {
  const event = req.body;
  
  // Verify signature (see below)
  // Process event
  
  res.status(200).send('OK');
});

2. Add Webhook in Dashboard

Go to Settings → Webhooks

Click "Add Webhook"

Enter your endpoint URL

Select events to listen for

Save (you'll receive a signing secret)

Add Webhook endpoint form

3. Verify Signatures

Always verify webhook signatures to ensure requests are from TIXFIN:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return signature === expectedSignature;
}

// In your webhook handler
const signature = req.headers['x-tixfin-signature'];
const isValid = verifySignature(
  JSON.stringify(req.body),
  signature,
  process.env.WEBHOOK_SECRET
);

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

Payload Structure

All webhooks follow this format:

{
  "id": "evt_xxxxxx",
  "type": "ticket.purchased",
  "created": 1612137600,
  "data": {
    // Event-specific data
  }
}

Example: Ticket Purchased

{
  "id": "evt_abc123",
  "type": "ticket.purchased",
  "created": 1612137600,
  "data": {
    "ticket_id": "tkt_xyz789",
    "event_id": "evt_456",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "ticket_type": "General Admission",
    "price": 50.00,
    "currency": "USD",
    "purchased_at": "2026-02-01T10:30:00Z"
  }
}

Example: Ticket Checked In

{
  "id": "evt_def456",
  "type": "ticket.checked_in",
  "created": 1612137700,
  "data": {
    "ticket_id": "tkt_xyz789",
    "event_id": "evt_456",
    "checked_in_at": "2026-02-08T18:45:00Z",
    "checked_in_by": "staff_user_123"
  }
}

Response Handling

Return 200 OK

Your endpoint must return 200 OK within 5 seconds:

app.post('/webhooks/tixfin', (req, res) => {
  // Process asynchronously
  processWebhook(req.body).catch(console.error);
  
  // Respond immediately
  res.status(200).send('OK');
});

Retry Logic

If your endpoint doesn't respond with 200:

TIXFIN retries after 5 minutes
Then after 1 hour
Then after 6 hours
Maximum 3 retries

Best Practices

✅ Do This

Process Asynchronously

// Queue for processing
await queue.add('webhook', event);
res.status(200).send('OK');

Handle Duplicates

// Check if already processed
if (await isProcessed(event.id)) {
  return res.status(200).send('OK');
}

Verify Signatures

// Always check authenticity
if (!verifySignature(payload, signature, secret)) {
  return res.status(401).send('Invalid');
}

Log Everything

logger.info('Webhook received', {
  eventId: event.id,
  type: event.type,
  timestamp: event.created
});

❌ Avoid This

Slow Processing

Don't process synchronously
Don't wait for external APIs
Don't run long operations

Missing Error Handling

Always use try-catch
Log errors properly
Return 200 even on error

No Validation

Always verify signatures
Check event types
Validate data structure

Testing

Test Webhook

Send test events from dashboard:

Go to Settings → Webhooks
Click webhook → "Send Test Event"
Check your endpoint receives it

Local Development

Use tools like ngrok to test locally:

# Start ngrok
ngrok http 3000

# Use ngrok URL in dashboard
https://abc123.ngrok.io/webhooks/tixfin

Troubleshooting

Webhook Not Received

Check:

Endpoint is publicly accessible (HTTPS)
Firewall allows TIXFIN IPs
Endpoint returns 200 OK
No errors in your logs

Invalid Signature

Check:

Using correct webhook secret
Verifying before parsing JSON
Not modifying payload
Header name is x-tixfin-signature

Security

Verify ALL Webhooks

Check signature on every request
Use HTTPS endpoints only
Keep webhook secret private
Rotate secrets periodically

IP Whitelist (Optional) Allow requests only from TIXFIN IPs:

Will be provided on request
Available on Enterprise plans

Need Help?

Issues with webhooks?

Check webhook logs in dashboard
View failed deliveries
Test with sample events

Contact Support:

Email: api@tixfin.com
Include: Webhook ID, event type, error logs
Response: Within 24 hours

API Overview

Getting started, use cases, rate limits

Authentication

API keys, security best practices

API Overview

Authentication

On this page