Webhooks

Rather than polling the API for changes, you can subscribe to webhooks. Getme sends an HTTP request to an endpoint you control whenever a relevant event occurs, such as an order being placed, a booking being confirmed, or a website publish request being applied.

Webhook delivery uses the same public identifier and API versioning model as the REST API. Event names, scopes, payload examples, and payload field summaries are generated from the public event contracts.

Event catalog

The generated event catalog is the source to use when choosing subscriptions for an endpoint. It groups public events by domain and links each event to its payload contract and example delivery.

Delivery shape

Every delivery uses a common event envelope. The exact data.object shape depends on the event type and is documented in the event catalog.

{
  "id": "wevt_Abcdef1234567890Ghijk",
  "object": "event",
  "api_version": "2026-06-09",
  "type": "booking.cancelled",
  "created": "2026-06-09T12:00:00Z",
  "environment": "test",
  "livemode": false,
  "data": {
    "object": {
      "id": "book_example",
      "object": "booking",
      "metadata": {
        "example": true
      }
    }
  }
}

Important fields:

• id — the public webhook event identifier.
• type — the event name, such as booking.cancelled.
• api_version — the API version used to shape the payload.
• environment — test or live.
• livemode — false for test deliveries and true for live deliveries.
• data.object — the event-specific public payload.

Payload contracts

Payloads only contain public-safe fields. Internal database IDs, secrets, and implementation-only fields are excluded before delivery and validated against the generated public webhook payload contracts.

Request headers

Getme signs each delivery and includes routing metadata in headers:

Content-Type: application/json
X-Getme-Signature: t=1781006400,v1=...
X-Getme-Event: booking.cancelled
X-Getme-Delivery: wdlv_Abcdef1234567890Ghijk
X-Getme-Api-Version: 2026-06-09
User-Agent: Getme-Webhooks/2026-05-24

Use X-Getme-Delivery and the event id for idempotency. A webhook can be delivered more than once after network errors, endpoint timeouts, or manual retry.

Verify signatures

Verify signatures against the raw request body bytes. Do not parse JSON before verification. The signature header is timestamped and uses the endpoint secret.

Node:

import {constructEvent} from "@getme-tech/getme-node/webhooks";

const event = constructEvent(rawBody, request.headers["x-getme-signature"], "whsec_...");

Python:

from getme.webhooks import construct_event

event = construct_event(raw_body, signature_header, "whsec_...")

Reject deliveries that fail signature verification. The SDK helpers use a default timestamp tolerance of five minutes.

Test and live mode

Keep test and live webhook endpoints separate:

• test endpoints receive events with environment: "test" and livemode: false;
• live endpoints receive events with environment: "live" and livemode: true;
• use gmat_test_* tokens for staging and test workspaces;
• use gmat_live_* tokens only for production workspaces.

Developer test workspaces cannot create or rotate live app-install tokens. The CLI also protects common host mismatches: staging expects test tokens and production expects live tokens.

Retries

Return a 2xx status only after the event is safely accepted. Network errors and non-2xx responses are retried until the delivery reaches its configured maximum attempt count.

Handlers should:

• verify X-Getme-Signature before processing;
• process events idempotently;
• avoid depending on delivery order across unrelated event types;
• return quickly and move long-running work to a queue.