Skip to main content
POST
/
api
/
public
/
v2
/
webhooks
cURL
curl --location 'https://www.headout.com/api/public/v2/webhooks/' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "url": "https://your-domain.com/webhooks/headout/booking-status",
  "enabled": true
}'

{
  "timestamp": 1756977070403,
  "message": "Webhook configuration created successfully"
}

​
Webhook Payload

Once your webhook is registered, Headout sends a POST request to your configured URL whenever a booking’s status changes. Your endpoint must respond within 45 seconds with an appropriate HTTP status code.

​
Sample Payload

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

​
Fields

FieldTypeDescription
bookingIdnumberUnique booking identifier. Use this to look up the booking via the Get Booking endpoint.
statusstringThe new status of the booking. Note: UNCAPTURED is never sent via webhook. See Booking Status.
eventTimestampstringTimestamp of when the status change occurred (local time). e.g. 2024-01-15T10:30:00. See ISO 8601.

​
Response & Retry Behavior

Your endpoint must return an HTTP response within 45 seconds (end-to-end call timeout).
  • 2xx — Delivery successful, no retry.
  • 4xx — Permanent failure, no retry.
  • 408, 429 — Retried (up to 4 times, same as 5xx).
  • 5xx — Retried up to 4 times with exponential backoff: 5s → 10s → 20s → 20s.

Authorizations

​
Headout-Auth
string
header
required

Body

application/json
​
url
string<uri>
required

HTTPS URL where webhooks will be delivered (must use HTTPS)

Required string length: 1 - 2048
Pattern: ^https://.*
Example:

"https://your-domain.com/webhooks/headout/booking-status"

​
enabled
boolean
default:true

Whether the webhook is active

Example:

true

Response

Webhook configuration created successfully

​
timestamp
integer

Response timestamp in milliseconds

Example:

1642248153000

​
message
string | null

Response message

Example:

"Webhook configuration created successfully"

​
error
object
​
data
object

Response data payload