Skip to main content
WEBHOOK

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

The booking.requested delivery. A guest paid for a stay the host still has to approve, so it landed pending.

​
event_id
string<uuid>
required

Stable across our retries. Use it to be idempotent.

​
event_type
enum<string>
required

Always booking.requested. Fixed on this schema, so narrowing on it alone hands you this one shape.

See BookingEventType for the seven transitions that carry this envelope.

Available options:
booking.requested,
booking.confirmed,
booking.rejected,
booking.checked_in,
booking.checked_out,
booking.cancelled,
booking.modified
Allowed value: "booking.requested"
​
occurred_at
string<date-time>
required

When the thing happened, stamped in the same transaction as the fact itself — not when we prepared this delivery. A backlog, a retry or a redrive does not move it, so it is safe to sort on; two events written in one transaction share an instant, which makes it a partial order rather than a sequence number. See https://developer.maatstays.wtf/guides/webhook-delivery#what-occurred_at-actually-is.

​
data
DeveloperBookingEvent · object
required

One moment in a booking's life. All seven booking.* events share this one shape; event_type on the envelope says which transition produced it and status says where the booking ended up.

There is no guest object and there never will be one. No name, no initial, no email, no user id, no reference of any kind. console_url is the honest pointer: follow it, sign in as a human, and see what a human may see.

There is also no amount_paid. The amount and its currency can only be paired correctly inside Maat's booking service, and none of these events carries the pair — GET /v1/bookings/{booking_reference} answers it.

​
test
boolean

Present, and true, only on a delivery you asked for with POST /webhooks/endpoint/test. Absent on every real event — never false. Branch on its presence if your handler must not act on the fixture.

Response

200

Return any 2xx to acknowledge.