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 thewebhooks.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.createdand amessage.created. - A viewing action that changes the request and persists a system thread message produces a
viewing_request.updatedand amessage.created. updatedincludes meaningful scheduling/terms changes even when the status value is unchanged.
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.
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.
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:- The partner is active and its endpoint is enabled with the captured configuration generation and designated key binding.
- The designated key is an active, unexpired,
partner-configuration key of the same partner holding an explicitenquiries:readpermission. A write-only key never implies read authority. - The captured landlord grant is still active, holds
enquiries:read, and itsconsent_revisionepoch 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. - The resource is still readable under the enquiry API’s explicit landlord/live/partner-created
scope; a
messageorofferadditionally belongs to its captured parent thread.
Signature verification (receiver contract)
The sender POSTs the exact stored bytes withContent-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:
- Decodes the base64 secret once to its raw 32 bytes (the admin discloses the base64 value once at creation or rotation).
- Recomputes the HMAC over
<received timestamp>.<exact received body bytes>— never a re-serialized object. - Compares with a constant-time function (e.g.
crypto.timingSafeEqual), and rejects a length mismatch. - Confirms the
Webhook-Idheader equals the bodyid. - Accepts timestamps within five minutes of its own clock. Both sides must keep working UTC clocks; a stale authentic request is rejected as replayed.
- Deduplicates by event
id, and persists durable acceptance before returning2xx. Further business processing may run asynchronously after that acceptance.
Executable example (Node.js 18+)
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
- 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_secretis disclosed once, in that response only, withCache-Control: no-store. - Share/install that secret with the partner’s receiver.
- Enable delivery explicitly. Only then do subsequent eligible events enrol; no earlier history is backfilled.
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 lookupPOST /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
404even with a valid secret; there is no public webhook-management endpoint.
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; fieldsevent_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
idand 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.Related
- 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.