# Your endpoint must answer the signed endpoint.challenge we POST
# to it DURING this call — see the webhooks guide.
curl --fail-with-body -X PUT https://maatstays.wtf/v1/webhooks/endpoint \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example-partner.invalid/maat",
"events": ["booking.confirmed", "booking.cancelled", "booking.requested"]
}'// Your endpoint must answer the signed endpoint.challenge we POST
// to it DURING this call — see the webhooks guide.
const res = await fetch('https://maatstays.wtf/v1/webhooks/endpoint', {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://hooks.example-partner.invalid/maat',
events: ['booking.confirmed', 'booking.cancelled', 'booking.requested'],
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
if (body.signing_secret) {
// Present only on the FIRST registration, and never shown again.
// Store it in your secret manager NOW. Never log it.
}
console.log(body.status); // 'active' once the challenge was echoed
import os
import requests
# Your endpoint must answer the signed endpoint.challenge we POST
# to it DURING this call — see the webhooks guide.
res = requests.put(
"https://maatstays.wtf/v1/webhooks/endpoint",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
json={
"url": "https://hooks.example-partner.invalid/maat",
"events": ["booking.confirmed", "booking.cancelled", "booking.requested"],
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
if "signing_secret" in body:
# Present only on the FIRST registration, and never shown again.
# Store it in your secret manager NOW. Never log it.
pass
print(body["status"]) # 'active' once the challenge was echoed
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
func main() {
// Your endpoint must answer the signed endpoint.challenge we POST
// to it DURING this call — see the webhooks guide.
payload, _ := json.Marshal(map[string]any{
"url": "https://hooks.example-partner.invalid/maat",
"events": []string{"booking.confirmed", "booking.cancelled", "booking.requested"},
})
req, _ := http.NewRequest(http.MethodPut,
"https://maatstays.wtf/v1/webhooks/endpoint",
bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body map[string]any
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("%v: %v", body["code"], body["detail"])
}
if _, ok := body["signing_secret"]; ok {
// Present only on the FIRST registration, and never shown again.
// Store it in your secret manager NOW. Never log it.
}
fmt.Println(body["status"]) // "active" once the challenge was echoed
}
{
"url": "https://hooks.example-partner.invalid/maat",
"events": [
"booking.confirmed",
"booking.cancelled",
"booking.requested"
],
"status": "active",
"signing_secret": "whsec_EXAMPLE_0000000000000000000000000000"
}Register where deliveries go
Sets the single HTTPS endpoint Maat delivers to, and the events you want. Sending this again replaces both — there is only ever one endpoint per workspace.
events must name at least one event. It used to be documented as accepting an
empty array to “pause” delivery, and it never did that: every registration
re-arms the challenge, so an empty one would leave your endpoint
pending_verification and subscribed to nothing. DELETE /v1/webhooks/endpoint
is the operation that means stop — it is idempotent, and it keeps your signing
secret and your delivery history.
The challenge round-trip
Nothing real is delivered until your endpoint proves it is yours. During this
call we POST a signed endpoint.challenge delivery to the URL you gave us, and
your handler must answer 2xx with a JSON body echoing the same challenge
string:
{ "challenge": "<the value we sent>" }
Echo it and the endpoint becomes active. Anything else — a non-2xx, an
unreadable body, a different value — leaves it pending_verification, and no
booking notification is ever sent to it. Call this endpoint again to retry.
The challenge is signed exactly like a real delivery, so your verification code is exercised before your first real payload rather than after it.
The challenge is re-armed on EVERY call, including one that does not change the URL. A URL that verified in March is not evidence about the same URL in September.
What we check about your URL
https only, on port 443 or 8443, on a publicly resolvable DNS name. We check the
address the name actually resolves to, at the moment we connect — not just at
registration — and we never follow redirects. If a URL is refused you get one
validation_failed; we do not report which check failed.
If your endpoint’s address later stops resolving publicly, we suspend it and stop delivering rather than retrying into it.
The signing secret
Returned once, in the response to this call, and never again — we do not store it in a form anything can read back. Re-registering (a corrected path, a new event list) deliberately does NOT mint a new one, so your existing verification keeps working.
If you lose it or it leaks, rotate it yourself with
POST /v1/webhooks/endpoint/rotate-secret: we issue the next secret and sign
every delivery with both for an overlap window, so you can deploy on your own
clock. See X-Signature-Previous under booking.confirmed.
Availability
Live in a sandbox workspace. Returns 501 against a production one, where
no endpoint is registered and nothing is delivered.
A 503 means webhook signing is not configured on our side. Nothing was
registered; retry.
# Your endpoint must answer the signed endpoint.challenge we POST
# to it DURING this call — see the webhooks guide.
curl --fail-with-body -X PUT https://maatstays.wtf/v1/webhooks/endpoint \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example-partner.invalid/maat",
"events": ["booking.confirmed", "booking.cancelled", "booking.requested"]
}'// Your endpoint must answer the signed endpoint.challenge we POST
// to it DURING this call — see the webhooks guide.
const res = await fetch('https://maatstays.wtf/v1/webhooks/endpoint', {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://hooks.example-partner.invalid/maat',
events: ['booking.confirmed', 'booking.cancelled', 'booking.requested'],
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
if (body.signing_secret) {
// Present only on the FIRST registration, and never shown again.
// Store it in your secret manager NOW. Never log it.
}
console.log(body.status); // 'active' once the challenge was echoed
import os
import requests
# Your endpoint must answer the signed endpoint.challenge we POST
# to it DURING this call — see the webhooks guide.
res = requests.put(
"https://maatstays.wtf/v1/webhooks/endpoint",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
json={
"url": "https://hooks.example-partner.invalid/maat",
"events": ["booking.confirmed", "booking.cancelled", "booking.requested"],
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
if "signing_secret" in body:
# Present only on the FIRST registration, and never shown again.
# Store it in your secret manager NOW. Never log it.
pass
print(body["status"]) # 'active' once the challenge was echoed
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
func main() {
// Your endpoint must answer the signed endpoint.challenge we POST
// to it DURING this call — see the webhooks guide.
payload, _ := json.Marshal(map[string]any{
"url": "https://hooks.example-partner.invalid/maat",
"events": []string{"booking.confirmed", "booking.cancelled", "booking.requested"},
})
req, _ := http.NewRequest(http.MethodPut,
"https://maatstays.wtf/v1/webhooks/endpoint",
bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body map[string]any
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("%v: %v", body["code"], body["detail"])
}
if _, ok := body["signing_secret"]; ok {
// Present only on the FIRST registration, and never shown again.
// Store it in your secret manager NOW. Never log it.
}
fmt.Println(body["status"]) // "active" once the challenge was echoed
}
{
"url": "https://hooks.example-partner.invalid/maat",
"events": [
"booking.confirmed",
"booking.cancelled",
"booking.requested"
],
"status": "active",
"signing_secret": "whsec_EXAMPLE_0000000000000000000000000000"
}Authorizations
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
HTTPS only, a public DNS name only. Checked against the address it resolves to at the moment we connect, on every delivery.
2048^https://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.
1 - 16 elementsWhat 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.
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.
The HTTPS URL deliveries are posted to.
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.
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 Whether the endpoint is delivering. A new or re-registered endpoint is pending_verification until it echoes the challenge.
See WebhookEndpointStatus.
pending_verification, active, suspended Returned once, on the call that issues it, and never again. Store it somewhere you can read it back; we cannot.