> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privetag.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Events
> B2A API webhook event reference
# Webhook Events
This page documents all webhook events sent by the B2A API.
For webhook setup and verification, see the [Webhooks Guide](/authentication/webhooks).
## 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:
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```mermaid theme={null}
graph LR
A[Recommendation] --> B[Booking]
B --> C[qr_verified]
C --> D[Ground Truth Updated]
D --> E[Better Future Recommendations]
```
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
```json theme={null}
{
"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
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```bash theme={null}
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
Always verify the `X-Privetag-Signature` header to ensure events are from PriveTag.
Use the event `id` for idempotency. Store processed IDs to avoid duplicate handling.
Return 200 immediately, process asynchronously. Webhook timeout is 30 seconds.
Log all incoming webhooks for debugging. Include the full payload and your processing result.
Set up alerts for webhook delivery failures. Check the webhook logs in your dashboard.
## Next Steps
Configure webhook endpoints
Learn about verified visit data