Developer Platform

Webhooks and event delivery

Push signed application events to external systems with retries, idempotency, and observable delivery history.

Scopes

account | app

Default

account

Transport

Signed HTTPS POST

Webhooks are the outbound event surface of the developer platform. Instead of repeatedly polling the REST API, an integration registers an HTTPS destination and receives events when relevant application activity occurs.

Open the Webhook Lab Receiver and polling walkthrough Download Developer Kit 1.20.3

Choose the subscription scope

Set scope to account for records and activity belonging only to the credential's organization. Set it to app when the SaaS builder's trusted backend must synchronize customer organizations and users across the whole SaaS app. Existing subscriptions default to account; changing scope is explicit.

Scope	Receives	Use it for
`account`	Matching events for the credential's own customer organization.	Ordinary record and account-local integrations. This is the backward-compatible default.
`app`	The nine organization, user, membership, and invitation lifecycle events for every customer organization in the SaaS app.	A SaaS builder's controlled billing, CRM, identity, or onboarding backend.

An app-scoped delivery still includes the customer organizationId. It does not give the receiver database access or permission to call APIs as that organization. App scope accepts only the nine lifecycle keys below; it cannot be paired with record events to bypass ordinary record scopes.

// Account-local record subscription (scope may be omitted)
{
  "displayName": "Account record sync",
  "destinationUrl": "https://hooks.example.com/records",
  "scope": "account",
  "events": [{ "eventKey": "record.updated", "eventVersion": "2026-08-01" }]
}

// App-wide customer lifecycle subscription
{
  "displayName": "Customer lifecycle sync",
  "destinationUrl": "https://hooks.example.com/lifecycle",
  "scope": "app",
  "events": [{ "eventKey": "organization.created", "eventVersion": "2026-09-14" }]
}

Organization and user lifecycle events

Event	Emitted when
`organization.created`	A customer organization is provisioned.
`organization.updated`	Name, billing email, status, or other published organization state changes, including reactivation.
`organization.deactivated`	The organization transitions to inactive.
`user.created`	A tenant user identity is created inside an organization.
`user.updated`	Published profile, type, owner, or active state changes, including reactivation.
`user.deactivated`	The user transitions to inactive.
`membership.created`	The user becomes a member of the organization.
`membership.role_changed`	User type, owner status, or DataRole assignments change.
`invitation.accepted`	A delivered invitation is consumed and linked to its accepted user.

These events use version 2026-09-14 and are classified as sensitive because they can contain names or email addresses. Subscribe only a controlled backend and retain only the fields your billing, CRM, identity, or onboarding workflow needs.

Event contract

Each delivery should have a stable event identifier, event type, schema version, occurrence time, application context, subject identifiers, and a data object. The event ID is the consumer's idempotency key.

{
  "id": "2a96f714-3653-4db4-bb63-7464bb5e4339",
  "type": "membership.role_changed",
  "version": "2026-09-14",
  "occurredAt": "2026-09-14T23:15:00Z",
  "appId": "7aa2...",
  "subject": {
    "type": "membership",
    "id": "e913..."
  },
  "actor": { "kind": "system" },
  "data": {
    "organizationId": "871c...",
    "userId": "e913...",
    "userTypeKey": "manager",
    "dataRoles": [{ "dataRoleId": 14 }]
  }
}

Current management routes

GET  /v1/apps/{saasAppId}/webhook-event-types
GET  /v1/apps/{saasAppId}/webhooks
POST /v1/apps/{saasAppId}/webhooks
PUT  /v1/apps/{saasAppId}/webhooks/{subscriptionId}
POST /v1/apps/{saasAppId}/webhooks/{subscriptionId}/rotate-secret
GET  /v1/apps/{saasAppId}/webhook-deliveries
POST /v1/apps/{saasAppId}/webhook-deliveries/{deliveryId}/retry

Receiving safely

Read the raw request body.
Verify the delivery signature and timestamp before trusting the JSON.
Reject payloads outside the replay window.
Use the event ID to make processing idempotent.
Return 2xx quickly and do heavy work asynchronously.

Verify X-BuildWithHQ-Timestamp and X-BuildWithHQ-Signature over the exact bytes received. The signed value is <timestamp>.<raw-body>; the signature uses HMAC-SHA256 and is formatted as v1=<lowercase-hex>. Reject timestamps more than five minutes from your server clock. Delivery and event identifiers are also supplied in X-BuildWithHQ-Delivery and X-BuildWithHQ-Event.

Delivery behavior

Lifecycle changes enter a transactional outbox with the database mutation, then the ordinary signed delivery worker promotes and delivers them. Multiple role writes inside one database transaction collapse to the final membership payload. Network failures still make delivery at-least-once rather than exactly-once: deduplicate by event ID and compare occurredAt or fetch current API state before applying an older event.

Developer operations

The API exposes event discovery, subscription create/update, signing-secret rotation, bounded delivery evidence, and manual retry of eligible failed deliveries. Failed attempts retain safe status, duration, category, and bounded response evidence rather than unbounded remote bodies.

Note

Event keys and versions come from the event-type endpoint. Do not hard-code an event catalog copied from prose, and do not retry a delivery unless its current state is eligible for the explicit retry operation.

Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.

Did this page answer your question?Tell us what’s missing