cURL

curl --fail-with-body -X POST https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret \
  -H "Authorization: Bearer $MAAT_PARTNER_TOKEN"

const res = await fetch(
    'https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret',
    {
        method: 'POST',
        headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
    },
);

const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);

// Store this NOW. It is never shown again.
console.log(body.signing_secret, body.previous_secret_expires_at);

import os

import requests

res = requests.post(
    "https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret",
    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')}")

# Store this NOW. It is never shown again.
print(body["signing_secret"], body["previous_secret_expires_at"])

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"
)

type payload struct {
    SigningSecret           string `json:"signing_secret"`
    PreviousSecretExpiresAt string `json:"previous_secret_expires_at"`
}

func main() {
    req, _ := http.NewRequest(http.MethodPost,
        "https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret", 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("rotate failed: %d", res.StatusCode)
    }

    var body payload
    if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
        log.Fatal(err)
    }
    // Store this NOW. It is never shown again.
    fmt.Println(body.SigningSecret, body.PreviousSecretExpiresAt)
}

{
  "endpoint": {
    "url": "https://hooks.example-partner.invalid/maat",
    "events": [
      "booking.confirmed",
      "booking.cancelled",
      "booking.requested"
    ],
    "status": "active",
    "verified_at": "2026-08-30T18:41:07.000Z",
    "challenge_sent_at": "2026-08-30T18:41:02.000Z",
    "last_challenge_error": null,
    "last_challenge_error_at": null,
    "secret_generation": 2,
    "previous_secret_expires_at": "2026-09-08T00:00:00.000Z",
    "created_at": "2026-08-30T18:41:02.000Z",
    "updated_at": "2026-09-07T09:00:00.000Z"
  },
  "signing_secret": "whsec_EXAMPLE_1111111111111111111111111111",
  "previous_secret_expires_at": "2026-09-08T00:00:00.000Z"
}

Webhooks

Rotate the signing secret

Issues a new signing secret and starts an overlap window in which we sign every delivery with both secrets, so you can deploy your new one on your own clock — see X-Signature-Previous under booking.confirmed.

The request body is empty, on purpose. There is no overlap_hours: how long we keep accepting the previous secret is a property of our own dispatcher, not a caller’s knob — a caller who could set it to zero would be choosing an outage they cannot see coming.

signing_secret is returned here, and nowhere else, ever. There is nowhere to read it back from afterward, so store it before you do anything else with this response.

This call is NOT idempotent, and a second one during the overlap is refused. We sign with exactly two secrets — your current one and the previous one, until its window closes — so rotating again inside that window would evict the secret you are verifying with today, including for deliveries already queued. A retry after a lost response therefore answers 409 rotation_in_progress with the instant the window closes, and your existing secret keeps working. Read that as proof the earlier call landed.

409 conflict when there is no endpoint registered to rotate a secret for — register one first with PUT /webhooks/endpoint. 503 means webhook signing is not configured on our side; nothing was rotated.

Live in a sandbox workspace. Returns 501 against a production one.

POST

webhooks

endpoint

rotate-secret

cURL

curl --fail-with-body -X POST https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret \
  -H "Authorization: Bearer $MAAT_PARTNER_TOKEN"

const res = await fetch(
    'https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret',
    {
        method: 'POST',
        headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
    },
);

const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);

// Store this NOW. It is never shown again.
console.log(body.signing_secret, body.previous_secret_expires_at);

import os

import requests

res = requests.post(
    "https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret",
    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')}")

# Store this NOW. It is never shown again.
print(body["signing_secret"], body["previous_secret_expires_at"])

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"
)

type payload struct {
    SigningSecret           string `json:"signing_secret"`
    PreviousSecretExpiresAt string `json:"previous_secret_expires_at"`
}

func main() {
    req, _ := http.NewRequest(http.MethodPost,
        "https://maatstays.wtf/v1/webhooks/endpoint/rotate-secret", 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("rotate failed: %d", res.StatusCode)
    }

    var body payload
    if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
        log.Fatal(err)
    }
    // Store this NOW. It is never shown again.
    fmt.Println(body.SigningSecret, body.PreviousSecretExpiresAt)
}

{
  "endpoint": {
    "url": "https://hooks.example-partner.invalid/maat",
    "events": [
      "booking.confirmed",
      "booking.cancelled",
      "booking.requested"
    ],
    "status": "active",
    "verified_at": "2026-08-30T18:41:07.000Z",
    "challenge_sent_at": "2026-08-30T18:41:02.000Z",
    "last_challenge_error": null,
    "last_challenge_error_at": null,
    "secret_generation": 2,
    "previous_secret_expires_at": "2026-09-08T00:00:00.000Z",
    "created_at": "2026-08-30T18:41:02.000Z",
    "updated_at": "2026-09-07T09:00:00.000Z"
  },
  "signing_secret": "whsec_EXAMPLE_1111111111111111111111111111",
  "previous_secret_expires_at": "2026-09-08T00:00:00.000Z"
}

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.

Response

The new secret. Present only in this response — store it now.

What POST /webhooks/endpoint/rotate-secret answers.

endpoint

DeveloperWebhookEndpoint · object

required

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.

Show child attributes

signing_secret

string

required

The new secret. Shown ONCE, here, and nowhere else — there is nowhere to read it back from afterward.

previous_secret_expires_at

string<date-time>

required

Until when the previous secret is still accepted.

Get started

Guides

Reference

Resources

API Reference

Rotate the signing secret

Authorizations

Response