Webhook Events

This page documents all webhook events sent by the B2A API.

For webhook setup and verification, see the Webhooks Guide.

Event Types

Event	Description	Trigger
`booking_confirmed`	Booking successfully created	After `/execute_booking` completes
`voucher_delivered`	Voucher email sent	After email delivery confirmed
`qr_verified`	User visited venue	When QR scanned at venue
`booking_cancelled`	Booking cancelled	On cancellation request
`booking_modified`	Booking details changed	On modification

Common Event Structure

All webhook events follow this structure:

{
  "id": "wh_evt_abc123def456",
  "event": "event_type",
  "api_version": "2025-01",
  "created_at": "2025-12-10T14:30:15Z",
  "data": {
    // Event-specific payload
  }
}

Field	Type	Description
`id`	string	Unique event identifier (for idempotency)
`event`	string	Event type
`api_version`	string	API version for payload format
`created_at`	string	ISO 8601 timestamp
`data`	object	Event-specific payload

booking_confirmed

Sent immediately after a booking is successfully created.

Payload

{
  "id": "wh_evt_abc123",
  "event": "booking_confirmed",
  "api_version": "2025-01",
  "created_at": "2025-12-10T14:30:15Z",
  "data": {
    "booking_id": "bkg_h7j9k2m4",
    "activity_id": "act_abc123",
    "activity_title": "Safari World Bangkok",
    "activity_category": "zoo",
    "user_email": "guest@example.com",
    "user_name": "John Doe",
    "booking_date": "2025-12-15",
    "num_adults": 2,
    "num_children": 0,
    "pricing": {
      "unit_price": 1500,
      "subtotal": 3000,
      "discount": 0,
      "total": 3000,
      "currency": "THB"
    },
    "context_log_id": "ctx_xyz789",
    "voucher_code": "PVT-2025-ABC123"
  }
}

Use Cases

Update your booking tracking system
Trigger confirmation notifications
Log booking analytics

voucher_delivered

Sent when the voucher email is successfully delivered.

Payload

{
  "id": "wh_evt_def456",
  "event": "voucher_delivered",
  "api_version": "2025-01",
  "created_at": "2025-12-10T14:30:45Z",
  "data": {
    "booking_id": "bkg_h7j9k2m4",
    "voucher_code": "PVT-2025-ABC123",
    "delivered_to": "guest@example.com",
    "delivered_at": "2025-12-10T14:30:43Z",
    "delivery_method": "email",
    "email_provider_id": "msg_xyz789"
  }
}

Use Cases

Confirm voucher delivery to user
Handle delivery failures (if no event received)
Track email delivery metrics

Timing

Typically sent within 30 seconds of booking creation.

qr_verified

This is the Ground Truth event - the most valuable for improving recommendations.

Sent when a user’s voucher QR code is scanned at the venue.

Payload

{
  "id": "wh_evt_ghi789",
  "event": "qr_verified",
  "api_version": "2025-01",
  "created_at": "2025-12-15T10:30:00Z",
  "data": {
    "booking_id": "bkg_h7j9k2m4",
    "activity_id": "act_abc123",
    "activity_title": "Safari World Bangkok",
    "context_log_id": "ctx_xyz789",
    "verified_at": "2025-12-15T10:30:00Z",
    "verification_method": "qr_scan",
    "venue_id": "ven_safari001",
    "venue_name": "Safari World Bangkok",
    "check_in_data": {
      "gate": "Main Entrance",
      "device_id": "scanner_001"
    }
  }
}

Use Cases

Track conversion from recommendation to visit
Measure AI agent recommendation quality
Trigger follow-up engagement (review requests, etc.)

Why This Matters

The qr_verified event closes the feedback loop, proving that your AI agent’s recommendation led to an actual visit.

booking_cancelled

Sent when a booking is cancelled.

Payload

{
  "id": "wh_evt_jkl012",
  "event": "booking_cancelled",
  "api_version": "2025-01",
  "created_at": "2025-12-12T09:15:00Z",
  "data": {
    "booking_id": "bkg_h7j9k2m4",
    "activity_id": "act_abc123",
    "cancelled_at": "2025-12-12T09:15:00Z",
    "cancellation_reason": "user_requested",
    "refund_status": "processed",
    "refund_amount": 3000,
    "currency": "THB"
  }
}

Cancellation Reasons

Reason	Description
`user_requested`	User cancelled via support
`venue_unavailable`	Venue closed or unavailable
`weather`	Weather-related cancellation
`system`	System-initiated cancellation

Use Cases

Update booking status in your system
Offer alternative recommendations
Track cancellation patterns

booking_modified

Sent when booking details are changed.

Payload

{
  "id": "wh_evt_mno345",
  "event": "booking_modified",
  "api_version": "2025-01",
  "created_at": "2025-12-11T16:00:00Z",
  "data": {
    "booking_id": "bkg_h7j9k2m4",
    "modified_at": "2025-12-11T16:00:00Z",
    "changes": {
      "booking_date": {
        "from": "2025-12-15",
        "to": "2025-12-16"
      },
      "num_adults": {
        "from": 2,
        "to": 3
      }
    },
    "new_pricing": {
      "unit_price": 1500,
      "subtotal": 4500,
      "discount": 0,
      "total": 4500,
      "currency": "THB"
    },
    "modified_by": "user"
  }
}

Use Cases

Keep booking records in sync
Notify users of successful changes
Track modification patterns

Event Filtering

Configure which events to receive when setting up webhooks:

{
  "webhook_url": "https://your-server.com/webhooks/privetag",
  "webhook_events": [
    "booking_confirmed",
    "qr_verified"
  ]
}

For most AI agent integrations, we recommend subscribing to:

booking_confirmed - Know when bookings succeed
qr_verified - Track Ground Truth for analytics

Webhook Delivery

Retry Schedule

Attempt	Delay
1st retry	5 seconds
2nd retry	30 seconds
3rd retry	2 minutes
4th retry	10 minutes
5th retry	1 hour

After 5 failed attempts, the event is marked as failed.

Headers

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Privetag-Signature: sha256=abc123...
X-Privetag-Event: booking_confirmed
X-Privetag-Delivery-Id: del_xyz789
User-Agent: PriveTag-Webhooks/1.0

Response Requirements

Return a 2xx status code to acknowledge receipt:

HTTP/1.1 200 OK

Any non-2xx response or timeout (> 30s) triggers a retry.

Testing Webhooks

Test Endpoint

Send test events to your webhook:

curl -X POST https://api.privetag.com/api/webhooks/test \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "booking_confirmed",
    "webhook_url": "https://your-server.com/webhooks/privetag"
  }'

Available Test Events

All event types can be tested:

booking_confirmed
voucher_delivered
qr_verified
booking_cancelled
booking_modified

Test events have "test": true in the payload.

Best Practices

Verify signatures

Always verify the X-Privetag-Signature header to ensure events are from PriveTag.

Handle duplicates

Use the event id for idempotency. Store processed IDs to avoid duplicate handling.

Respond quickly

Return 200 immediately, process asynchronously. Webhook timeout is 30 seconds.

Log everything

Log all incoming webhooks for debugging. Include the full payload and your processing result.

Monitor failures

Set up alerts for webhook delivery failures. Check the webhook logs in your dashboard.

B2A API

Webhook Events

Webhook Events

Event Types

Common Event Structure

booking_confirmed

Payload

Use Cases

voucher_delivered

Payload

Use Cases

Timing

qr_verified

Payload

Use Cases

Why This Matters

booking_cancelled

Payload

Cancellation Reasons

Use Cases

booking_modified

Payload

Use Cases

Event Filtering

Webhook Delivery

Retry Schedule

Headers

Response Requirements

Testing Webhooks

Test Endpoint

Available Test Events

Best Practices

Next Steps

Webhooks Setup

Ground Truth

B2A API

​Webhook Events

​Event Types

​Common Event Structure

​booking_confirmed

​Payload

​Use Cases

​voucher_delivered

​Payload

​Use Cases

​Timing

​qr_verified

​Payload

​Use Cases

​Why This Matters

​booking_cancelled

​Payload

​Cancellation Reasons

​Use Cases

​booking_modified

​Payload

​Use Cases

​Event Filtering

​Webhook Delivery

​Retry Schedule

​Headers

​Response Requirements

​Testing Webhooks

​Test Endpoint

​Available Test Events

​Best Practices

​Next Steps

Webhooks Setup

Ground Truth

Webhook Events

Event Types

Common Event Structure

booking_confirmed

Payload

Use Cases

voucher_delivered

Payload

Use Cases

Timing

qr_verified

Payload

Use Cases

Why This Matters

booking_cancelled

Payload

Cancellation Reasons

Use Cases

booking_modified

Payload

Use Cases

Event Filtering

Webhook Delivery

Retry Schedule

Headers

Response Requirements

Testing Webhooks

Test Endpoint

Available Test Events

Best Practices

Next Steps