Skip to main content
PUT
cURL

Authorizations

Authorization
string
header
required

A short-lived partner token, obtained by exchanging your API key at POST /token. Send it as Authorization: Bearer <access_token>.

Tokens live for fifteen minutes by default and never for more than an hour. Mint one per batch of work, not one per request.

The token carries the workspace and the environment its key was issued for. You cannot change either by asking: the exchange ignores everything in the request body for exactly that reason.

It also carries the key's scopes (scope, a list). Every operation names a scope as x-maat-scope, and a token whose key lacks it is refused with 403 insufficient_scope, naming the scope. Scopes are fixed when a key is issued and are re-read from the key on every request, so a key narrowed today is narrowed on its next call — the token's scope is what the key held at exchange time, for your own reading, never what authorizes a request.

x-maat-scope is the floor, and on the quick-action operations it is not the whole requirement. PUT and DELETE /listings/{listing_id}/quick-actions/{template_key} carry rules:write, and additionally require pricing:write when template_key begins pricing. — the capability depends on the template in the path, because a cleaning fee changes what a guest pays and a minimum stay does not. The refusal is the same 403 insufficient_scope, naming pricing:write. The two READS apply the same requirement without erroring: GET /listings/{listing_id}/quick-actions still lists the pricing.* rows but withholds their applied state, and GET /listings/{listing_id}/rules omits the pricing rules entirely and reports pricing_withheld in warnings. These four are the only operations in this document whose requirement is not exactly their x-maat-scope, and each of them says so machine-readably: x-maat-scope-additional lists the second scope it can require and x-maat-scope-additional-when says what happens without it.

Never send it as a cookie or in a query string, and never store it — store the API key, mint tokens from it.

Body

application/json
url
string<uri>
required

HTTPS only, a public DNS name only. Checked against the address it resolves to at the moment we connect, on every delivery.

Maximum string length: 2048
Pattern: ^https://
events
enum<string>[]
required

At least one. An empty array is refused: every registration re-arms the challenge, so an empty one would leave the endpoint pending_verification and subscribed to nothing. DELETE /v1/webhooks/endpoint is the operation that means stop.

Naming an event your credential cannot receive is 400 validation_failed, and the detail names them — see WebhookEventType.

See WebhookEventType.

Required array length: 1 - 16 elements

What you can subscribe to. Every event is available to every key; you receive the ones your endpoint registered for, about your own workspace's inventory. Registering for a value not on this list answers 400 validation_failed and names the event.

Available options:
booking.confirmed,
booking.cancelled,
booking.requested,
booking.rejected,
booking.checked_in,
booking.checked_out,
booking.modified,
review.created,
listing.published,
listing.unlisted,
pricing.mode_changed,
pricing.currency_changed,
calendar.held,
calendar.released

Response

The endpoint is registered. Check status: active means the challenge was echoed and deliveries will flow; pending_verification means it was not, and nothing will be sent until you call again and echo it.

signing_secret is present only the FIRST time you register. Its absence on a later call is not an error — your existing secret still applies.

url
string<uri>
required

The HTTPS URL deliveries are posted to.

events
enum<string>[]
required

The event types this endpoint is subscribed to.

See WebhookEventType.

What you can subscribe to. Every event is available to every key; you receive the ones your endpoint registered for, about your own workspace's inventory. Registering for a value not on this list answers 400 validation_failed and names the event.

Available options:
booking.confirmed,
booking.cancelled,
booking.requested,
booking.rejected,
booking.checked_in,
booking.checked_out,
booking.modified,
review.created,
listing.published,
listing.unlisted,
pricing.mode_changed,
pricing.currency_changed,
calendar.held,
calendar.released
status
enum<string>
required

Whether the endpoint is delivering. A new or re-registered endpoint is pending_verification until it echoes the challenge. See WebhookEndpointStatus.

Available options:
pending_verification,
active,
suspended
signing_secret
string

Returned once, on the call that issues it, and never again. Store it somewhere you can read it back; we cannot.