Skip to main content

​
Webhooks

Receive real-time notifications when events occur in your Tiquo account.

​
Overview

Webhooks allow your application to:
  • React to events in real-time
  • Sync data with external systems
  • Trigger automated workflows
  • Maintain data consistency

​
How Webhooks Work

  1. Event Occurs - Something happens in Tiquo
  2. Webhook Triggered - Tiquo sends HTTP POST
  3. Your Server Receives - Process the event
  4. Acknowledge - Return 2xx status

​
Setting Up Webhooks

1

Create Endpoint

Set up an HTTPS endpoint on your server
2

Register Webhook

Go to Settings → Webhooks → Add Webhook
3

Configure Events

Select which events to receive
4

Save Signing Secret

Copy the signing secret for verification
5

Test

Use the test button to verify setup

​
Available Events

​
Customer Events

EventDescription
customer.createdNew customer created
customer.updatedCustomer profile updated
customer.deletedCustomer deleted

​
Order Events

EventDescription
order.createdNew order/booking created
order.updatedOrder updated
order.confirmedOrder confirmed
order.completedOrder completed
order.cancelledOrder cancelled

​
Payment Events

EventDescription
payment.succeededPayment processed
payment.failedPayment failed
payment.refundedPayment refunded

​
Loyalty Events

EventDescription
loyalty.points_earnedPoints added
loyalty.points_redeemedPoints used
loyalty.tier_changedCustomer tier changed

​
Webhook Payload

​
Standard Format

{
  "id": "evt_abc123",
  "type": "order.created",
  "created": "2024-01-20T14:30:00Z",
  "data": {
    "id": "ord_xyz789",
    "type": "booking",
    "status": "confirmed",
    "customerId": "cust_123",
    "total": 81.56
  }
}

​
Headers

HeaderDescription
X-Tiquo-SignatureHMAC signature
X-Tiquo-TimestampUnix timestamp
X-Tiquo-EventEvent type
Content-Typeapplication/json

​
Verifying Webhooks

Always verify webhook signatures: 
const crypto = require('crypto');

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

// In your handler
app.post('/webhooks/tiquo', (req, res) => {
  const signature = req.headers['x-tiquo-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  const event = req.body;
  console.log('Received event:', event.type);
  
  res.status(200).send('OK');
});
Never process webhooks without verifying the signature.

​
Responding to Webhooks

​
Success Response

Return 2xx status code: 
res.status(200).send('OK');

​
Failure Handling

If you return non-2xx or timeout:
  • Tiquo retries the webhook
  • Exponential backoff: 1m, 5m, 30m, 2h, 12h
  • Maximum 5 retries
  • Failed webhooks visible in dashboard

​
Best Practices

Return 200 immediately, process async:
app.post('/webhooks', async (req, res) => {
  // Acknowledge immediately
  res.status(200).send('OK');
  
  // Process in background
  processWebhook(req.body);
});
Webhooks may be sent multiple times. Use id for idempotency:
if (await isProcessed(event.id)) {
  return; // Already handled
}
await markProcessed(event.id);
await handleEvent(event);
Log webhook receipts for debugging:
console.log(`Received ${event.type}: ${event.id}`);
Always use HTTPS endpoints for webhooks.

​
Testing Webhooks

​
Test Button

Use the dashboard test button:
  1. Go to Settings → Webhooks
  2. Click Test next to your webhook
  3. Check your endpoint receives it

​
Local Development

Use a tunnel for local testing: 
# Using ngrok
ngrok http 3000

# Use the ngrok URL as webhook endpoint

​
Webhook Logs

View webhook history:
  1. Go to Settings → Webhooks
  2. Click webhook to see logs
  3. View deliveries and responses

Customer Events

Customer webhook events

Order Events

Order webhook events