Partner API Webhooks

Partner API webhooks are outbound version-1 callbacks the Go backend sends to a partner’s own receiver when enquiry resources change on a landlord’s live, partner-created property. They complement the pull API: the callback is a signal, and the partner reads current state through the existing authorised endpoints. The machine-readable publication is the webhooks.partnerEvent entry (with the WebhookEnvelope and WebhookEnvelopeResource schemas) in backend/go/openapi/partner-v1.yaml. This guide is the prose contract; the two must agree.
  • One callback configuration per partner, admin-managed only — there is no partner self-service, replay, redelivery or test-send route.
  • Five event types, one immutable UTF-8 JSON body each, HMAC-SHA256 signed.
  • Bounded at-least-once delivery: duplicates, delays and out-of-order arrival are expected. There is no exactly-once guarantee and no promise of eventual receipt from an unavailable receiver.

Event catalogue

One occurrence is captured per changed resource, not per HTTP request:
  • Creating a request together with its initial message produces a viewing_request.created and a message.created.
  • A viewing action that changes the request and persists a system thread message produces a viewing_request.updated and a message.created.
  • updated includes meaningful scheduling/terms changes even when the status value is unchanged.
Exclusions. No event is emitted for rejected validation/authorisation, rolled-back work, idempotent message replays, successful unchanged confirmation retries, timestamp-only writes, message read receipts, reminder bookkeeping or internal moderation fields. Reads never emit events or change message read state. Own-actor events. The subscribing partner’s own actions are not suppressed: a partner’s own change to a viewing request or thread still produces the corresponding callback.

Envelope (version 1)

Every callback body is one UTF-8 JSON object, serialized once per occurrence and reused byte-for-byte for every attempt and retry: The payload deliberately contains no tenant identifiers, names or contacts, message bodies, viewing times, offer terms, actor details, authorisation revisions or internal routing metadata. The event adds no business transition and no system message.
(The identifiers above are fabricated examples.)

Fetching current state — no snapshots

An event does not carry the changed content and there is no single-message endpoint. After receiving a callback, read current state through the existing authorised endpoints:
  • GET /api/partner/v1/landlords/{landlord_id}/viewing-requests/{id} — current request detail.
  • GET /api/partner/v1/landlords/{landlord_id}/viewing-requests/{id}/messages — the thread page.
  • GET /api/partner/v1/landlords/{landlord_id}/offers/{id} — current offer detail.
A later API response may reflect further changes, or deny access that has since been revoked. Archive visibility follows the enquiry API’s existing readable behaviour: webhook eligibility introduces no extra blanket archive exclusion. A change that occurs between the event and the fetch is simply visible in the fetched state. In-flight limitation. Eligibility is re-checked immediately before each send, but a check cannot recall a request already in flight or identifiers the partner has already received.

Eligibility — who receives a callback

A callback is delivered only while all of the following hold, both when the occurrence is routed and again immediately before each attempt:
  1. The partner is active and its endpoint is enabled with the captured configuration generation and designated key binding.
  2. The designated key is an active, unexpired, partner-configuration key of the same partner holding an explicit enquiries:read permission. A write-only key never implies read authority.
  3. The captured landlord grant is still active, holds enquiries:read, and its consent_revision epoch exactly matches the value frozen at capture. Reapproval that keeps read permission still increments the revision, so older work does not leak through restored active status.
  4. The resource is still readable under the enquiry API’s explicit landlord/live/partner-created scope; a message or offer additionally belongs to its captured parent thread.
Newly enabled endpoints or newly approved grants never enrol an older occurrence. An occurrence captured with no eligible audience is terminal at capture and is never delivered.

Signature verification (receiver contract)

The sender POSTs the exact stored bytes with Content-Type: application/json and three headers: The signature is HMAC-SHA256 of the bytes <Webhook-Timestamp>.<exact JSON body>, keyed by the raw 32-byte signing secret. Retries reuse the same id/body and recompute a fresh timestamp/signature. A conforming receiver:
  1. Decodes the base64 secret once to its raw 32 bytes (the admin discloses the base64 value once at creation or rotation).
  2. Recomputes the HMAC over <received timestamp>.<exact received body bytes> — never a re-serialized object.
  3. Compares with a constant-time function (e.g. crypto.timingSafeEqual), and rejects a length mismatch.
  4. Confirms the Webhook-Id header equals the body id.
  5. Accepts timestamps within five minutes of its own clock. Both sides must keep working UTC clocks; a stale authentic request is rejected as replayed.
  6. Deduplicates by event id, and persists durable acceptance before returning 2xx. Further business processing may run asynchronously after that acceptance.

Executable example (Node.js 18+)

Exercised against real signed bytes (secret = demo bytes 01…20; the signature below was produced by the shipping sender and independently reproduced with openssl dgst -sha256 -mac HMAC):

Admin onboarding lifecycle

Configuration lives under the existing rental platform-admin boundary at /api/rental/admin/partners/:id/webhook (the panel calls its same-origin proxy). There is no partner self-service route. SafeWebhookConfig = {partner_id, url, key_id, enabled, generation, has_signing_secret, created_at, updated_at} — never ciphertext, nonce or the raw secret. Enabled edits/rebinding/ rotation return 409 with code webhook_disable_required. Onboarding sequence
  1. Create the endpoint with a validated absolute public HTTPS URL and a designated active/unexpired/read-capable key of the same partner. It is created disabled and its base64 signing_secret is disclosed once, in that response only, with Cache-Control: no-store.
  2. Share/install that secret with the partner’s receiver.
  3. Enable delivery explicitly. Only then do subsequent eligible events enrol; no earlier history is backfilled.
Editing, rebinding and rotation require disabling. Lifecycle changes — configuration change, enable/disable and rotation — invalidate the enrollment generation, so outstanding work tied to the old enrollment is suppressed even if the same URL or key is reselected. A lost creation response cannot reveal an existing secret; recovery is an explicit disabled rotation (there is no secret-reveal endpoint and no dual-secret overlap). No disabled-interval backfill. Events during a disabled interval are not enrolled and are not replayed: re-enabling starts a new enrollment and changes during the interval require API reconciliation. Generation suppression also applies to config changes while disabled. signing_secret is 32 cryptographically random bytes, encrypted at rest with the shared AES-256-GCM primitive using fresh nonces. Missing/invalid wrapping-key crypto never falls back to plaintext storage or unsigned sends — the dependent operation or dispatch fails safely.

Delivery bounds and outcomes

Transport uses normal certificate verification and a 10-second total timeout; no environment proxy, redirect follow, cookie/API credential, private-network mode or TLS bypass. Receiver failures never automatically disable an endpoint. Duplicate semantics. A receiver may accept an event and lose the acknowledgement before the sender records it, so the same id/body can be sent again (with a fresh timestamp/signature). This is bounded at-least-once — not exactly-once, and not a guarantee of eventual receipt from an unavailable receiver. Delivery is unordered: do not assume order. There is no manual replay/redelivery and no synthetic test-send.

Key authority — private Bun dependency

Before creating a delivery and immediately before every send, Go obtains read-only key facts from Bun over the private metadata lookup POST /api/internal/partner/api-keys/metadata, authenticated with the shared x-service-secret. It returns exactly {key_id, partner_id, config_id, permissions, enabled, expires_at} and:
  • never consumes partner request quota — repeated lookups leave usage counters unchanged;
  • never returns or stores raw keys/hashes;
  • is mounted on the internal listener only — the public listener returns 404 even with a valid secret; there is no public webhook-management endpoint.
Eligibility requires matching partner_id/key_id, config_id: partner, enabled, unexpired, and an explicit enquiries:read permission. Definitive absence/foreign ownership/wrong configuration is 404 partner_key_not_found and denies; a service/transport/unusable-response fault is operational failure (503 auth_unavailable) and defers — it never grants access and is never treated as the partner having lost consent. Ownership separation. Bun owns the private lookup contract and its documentation (Internal Service API); Go owns callback delivery and this receiver contract; the panel owns its admin form, secret disclosure and history UI. Go delegates key authority to Bun and never reads Better Auth key tables.

Reconciliation

Webhooks are best-effort signals, so never treat the stream as a complete ledger:
  • Initial sync. On first enable, fetch current state for the landlord’s live, partner-created enquiries through the normal API reads; no history is backfilled.
  • Gaps from a disabled interval or terminal failure. Inspect terminal outcomes in GET /api/rental/admin/partners/:id/webhook/deliveries (bounded, offset-paginated; fields event_id, event_type, status, attempt_count, created_at, last_attempt_at, next_attempt_at, finished_at, last_http_status, last_error_code), then reconcile by API reads — there is no replay.
  • Delayed/duplicate notifications. Deduplicate by id and fetch current state; a fetch after further changes returns the newer state, and a revoked access returns the API’s existing denial.

Non-goals

No developer portal/self-service; no other resource families (property/listing/tenancy/payment/ handover); no offer writes; no full resource snapshots; no actor suppression; no event filters; no multiple/per-landlord endpoints; no external message broker; no strict ordering; no exactly-once delivery; no eventual-receipt guarantee; no historical backfill/replay; no manual redelivery; no synthetic test-event tooling; no analytics dashboards; no private-network callbacks or TLS bypass.
  • Machine-readable contract: backend/go/openapi/partner-v1.yaml → webhooks.partnerEvent.
  • Private key lookup: Internal Service API.
  • Partner enquiry pull API: the same OpenAPI file (openapi/partner-v1.yaml).
  • Source design: docs/superpowers/specs/2026-10-09-partner-api-webhooks-design.md.