Skip to navigation
BookingExperience Booking APIwebhooks

Headout Booking Status Webhook

🔔 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:

{
  "bookingId": 123456789,
  "status": "COMPLETED",
  "eventTimestamp": "2024-01-15T10:30:00"
}

🔄 Status Mapping

Headout StatusInternal StatusDescription
UNCAPTUREDPENDINGBooking created but not yet captured
PENDINGPENDINGCaptured, waiting for fulfillment
COMPLETEDCONFIRMEDBooking fulfilled successfully
CANCELLEDCANCELLEDBooking was cancelled
FAILEDREJECTEDBooking failed (payment/system error)
CAPTURE_TIMEDOUTREJECTEDCapture 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
successbooleanOptional
messagestringOptional
bookingIdstringOptional
oldStatusstringOptional
newStatusstringOptional
headoutStatusstringOptional
timestampstringOptional

Errors

400
Bad Request Error
500
Internal Server Error