ETERA API Documentation

🔔 Headout Booking Status Webhook Handler

Receives real-time booking status updates from Headout API and synchronizes them with the local booking database.

📋 Webhook Payload

1 {
2   "bookingId": 123456789,
3   "status": "COMPLETED",
4   "eventTimestamp": "2024-01-15T10:30:00"
5 }

🔄 Status Mapping

Headout Status	Internal Status	Description
UNCAPTURED	PENDING	Booking created but not yet captured
PENDING	PENDING	Captured, waiting for fulfillment
COMPLETED	CONFIRMED	Booking fulfilled successfully
CANCELLED	CANCELLED	Booking was cancelled
FAILED	REJECTED	Booking failed (payment/system error)
CAPTURE_TIMEDOUT	REJECTED	Capture did not happen within allowed time

🎯 Functionality

✅ Status Synchronization: Updates local booking status
✅ Timestamp Tracking: Records completion/cancellation times
✅ Idempotency: Handles duplicate webhook deliveries
✅ Error Handling: Graceful error responses
✅ Logging: Comprehensive webhook processing logs

🔒 Security

Validates required payload fields
Returns appropriate HTTP status codes
Logs all webhook attempts for auditing

📊 Response Codes

200: Webhook processed successfully
400: Invalid payload or missing fields
500: Internal server error

**🔔 Headout Booking Status Webhook Handler** Receives real-time booking status updates from Headout API and synchronizes them with the local booking database. ## 📋 **Webhook Payload** Based on [Headout API documentation](https://developers.headout.com/docs/api/#tag/Webhooks): ```json { "bookingId": 123456789, "status": "COMPLETED", "eventTimestamp": "2024-01-15T10:30:00" } ``` ## 🔄 **Status Mapping** | Headout Status | Internal Status | Description | |---------------|----------------|-------------| | UNCAPTURED | PENDING | Booking created but not yet captured | | PENDING | PENDING | Captured, waiting for fulfillment | | COMPLETED | CONFIRMED | Booking fulfilled successfully | | CANCELLED | CANCELLED | Booking was cancelled | | FAILED | REJECTED | Booking failed (payment/system error) | | CAPTURE_TIMEDOUT | REJECTED | Capture did not happen within allowed time | ## 🎯 **Functionality** - ✅ **Status Synchronization**: Updates local booking status - ✅ **Timestamp Tracking**: Records completion/cancellation times - ✅ **Idempotency**: Handles duplicate webhook deliveries - ✅ **Error Handling**: Graceful error responses - ✅ **Logging**: Comprehensive webhook processing logs ## 🔒 **Security** - Validates required payload fields - Returns appropriate HTTP status codes - Logs all webhook attempts for auditing ## 📊 **Response Codes** - **200**: Webhook processed successfully - **400**: Invalid payload or missing fields - **500**: Internal server error

Authentication

AuthorizationBearer

JWT token from @etera-ai/auth package (auth.etera.dev) - Format: Bearer <token>

Request

This endpoint expects an object.

bookingIddoubleRequired

status"UNCAPTURED" or "PENDING" or "COMPLETED" or "CANCELLED" or "FAILED" or "CAPTURE_TIMEDOUT"Required

eventTimestampstringRequired

Response

Webhook processed successfully

successboolean or null

messagestring or null

bookingIdstring or null

oldStatusstring or null

newStatusstring or null

headoutStatusstring or null

timestampstring or null

Errors