curl --fail-with-body https://maatstays.wtf/v1/webhooks/endpoint \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"
const res = await fetch('https://maatstays.wtf/v1/webhooks/endpoint', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
if (body === null) {
console.log('no endpoint registered yet');
} else {
console.log(body.url, body.status);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/webhooks/endpoint",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
if body is None:
print("no endpoint registered yet")
else:
print(body["url"], body["status"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type endpointView struct {
URL string `json:"url"`
Status string `json:"status"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/webhooks/endpoint", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode >= 400 {
log.Fatalf("read failed: %d", res.StatusCode)
}
var body *endpointView
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if body == nil {
fmt.Println("no endpoint registered yet")
} else {
fmt.Println(body.URL, body.Status)
}
}
Read your endpoint back
Reads back the endpoint you registered with PUT /webhooks/endpoint, as the
whole body — there is no wrapper object.
The body is null — not a 404 — when nothing is registered. An endpoint you
have not set up yet is a normal state for a new integration, not an error.
No secret is ever returned here. The row stores a generation number, not the secret itself; the value is returned only by the call that mints it — the first registration, or a rotation — and nowhere else, ever.
Live in a sandbox workspace. Returns 501 against a production one.
curl --fail-with-body https://maatstays.wtf/v1/webhooks/endpoint \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"
const res = await fetch('https://maatstays.wtf/v1/webhooks/endpoint', {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
if (body === null) {
console.log('no endpoint registered yet');
} else {
console.log(body.url, body.status);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/webhooks/endpoint",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
if body is None:
print("no endpoint registered yet")
else:
print(body["url"], body["status"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type endpointView struct {
URL string `json:"url"`
Status string `json:"status"`
}
func main() {
req, _ := http.NewRequest(http.MethodGet, "https://maatstays.wtf/v1/webhooks/endpoint", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode >= 400 {
log.Fatalf("read failed: %d", res.StatusCode)
}
var body *endpointView
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if body == nil {
fmt.Println("no endpoint registered yet")
} else {
fmt.Println(body.URL, body.Status)
}
}
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.
Response
Your endpoint, or null if you have not registered one.
Your own delivery endpoint, read back.
There is no secret here, and there cannot be: the row stores a GENERATION number, and the secret itself is derived from it and a value that lives only in our own environment. It is returned once — at registration, or at rotation — and nowhere else, ever.
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 re-registration returns it to pending_verification until the new challenge is echoed.
See WebhookEndpointStatus.
pending_verification, active, suspended When the challenge was echoed. null while it has not been.
When we last POSTed the challenge to this URL.
A code from a closed vocabulary (challenge_mismatch, http_error, …),
never a message and never your own response body.
When the last failed challenge was attempted, or null if none has failed.
Which generation of the signing secret deliveries are signed with.
Until when the PREVIOUS secret is still accepted alongside the current
one. null outside a rotation.
When the endpoint was first registered.
When the registration was last changed — a re-registration, a rotation or a status change.