Webhook Reference
Detailed documentation for all BeTS webhook endpoints, including payload formats and authentication requirements.
Authentication
All webhook endpoints support optional Bearer token authentication. Set the corresponding environment variable to enable authentication.
Authorization: Bearer YOUR_WEBHOOK_SECRETArcade Weekly Import
Import weekly game activity data from card systems like Embed.
/api/arcade/webhook/weekly-importARCADE_WEBHOOK_SECRETRequest Payload
{
"info": {
"store": "Fun Zone Downtown",
"weekStart": "2024-03-11",
"weekEnd": "2024-03-17",
"filename": "weekly-report.xlsx"
},
"data": [
{
"game_ml_id": "DEMO-SB-001",
"game_name": "Space Blaster",
"customer_plays": "450",
"game_value": "225.00",
"tickets_enabled": "1",
"e_tickets": "5000"
}
]
}Success Response
{
"success": true,
"imported": 1,
"skipped": 0
}Events Import
Import parsed event data, typically from n8n after PDF extraction.
/api/events/webhookEVENTS_WEBHOOK_SECRETRequest Payload
{
"sessionId": "unique-session-id",
"locationId": "optional-location-id",
"events": [
{
"name": "Birthday Party - Smith",
"venue": "Fun Zone Downtown",
"contacts": [
{
"name": "John Smith",
"email": "john@example.com",
"phone": "555-1234",
"role": "Primary"
}
],
"schedule": [
{
"date": "2024-03-15",
"time": "2:00 PM",
"function": "Arrival",
"count": 20
},
{
"date": "2024-03-15",
"time": "2:30 PM",
"function": "Food Service",
"count": 20
}
],
"lineItems": [
{
"category": "Food",
"item": "Pizza Package",
"qty": 2,
"price": 50
}
]
}
]
}Success Response
{
"success": true,
"imported": 1,
"skipped": 0
}Feedback Import
Import guest feedback from external survey tools.
/api/feedback/webhookFEEDBACK_WEBHOOK_SECRETRequest Payload
{
"feedback": [
{
"locationName": "Fun Zone Downtown",
"rating": 4,
"category": "Staff",
"message": "Great service from the team!",
"guestName": "Happy Guest",
"guestEmail": "guest@example.com",
"source": "Survey",
"submittedAt": "2024-03-15T14:30:00Z"
}
]
}Success Response
{
"success": true,
"imported": 1,
"skipped": 0
}Inventory Import
Import master items and location inventory for redemption.
/api/inventory/webhookINVENTORY_WEBHOOK_SECRETRequest Payload
{
"masterItems": [
{
"sku": "PLU-001",
"name": "Small Plush Bear",
"barcode": "123456789012",
"defaultTicketValue": 50,
"unitCost": 1.50,
"categoryCode": "PLUSH"
}
],
"locationInventory": [
{
"locationName": "Fun Zone Downtown",
"sku": "PLU-001",
"qtyCounted": 25,
"parLevel": 30
}
]
}Success Response
{
"success": true,
"imported": 1,
"skipped": 0
}Bar Inventory Import
Import bar bottles and location bar inventory.
/api/bar/webhookBAR_WEBHOOK_SECRETRequest Payload
{
"barBottles": [
{
"name": "House Vodka",
"brand": "Demo Spirits",
"type": "Vodka",
"abv": 40,
"volume": 750,
"unitCost": 15.00
}
],
"locationBarInventory": [
{
"locationName": "Fun Zone Downtown",
"bottleName": "House Vodka",
"bottleBrand": "Demo Spirits",
"onHand": 5,
"parLevel": 8,
"currentLevel": 75
}
]
}Success Response
{
"success": true,
"imported": 1,
"skipped": 0
}Data Validation
All webhook endpoints validate incoming data before processing. Common validation rules include:
- Required fields must be present and non-empty
- Location names must match existing locations in BeTS
- Numeric values must be within expected ranges
- References (SKUs, game IDs) must exist before creating dependent records
- Dates must be in valid ISO 8601 or recognizable formats
Error Handling
When validation fails or an error occurs, the webhook returns an error response with details about the issue.
{
"success": false,
"error": "Location not found",
"details": {
"field": "locationName",
"value": "Unknown Venue",
"suggestion": "Available locations: Fun Zone Downtown, Fun Zone Mall"
}
}Partial Failures
When processing multiple records, some may succeed while others fail. The response includes counts of imported, skipped, and failed records along with error details for failures.