5.4.2.5 Webhooks
The Webhooks domain of access. How the platform's events reach systems outside it (decided 2026-10-30, D9). An Organization registers where it wants its events: an HTTPS endpoint, which Pub/Sub calls with a Google-signed token (a push subscription), or a Google Cloud service account that pulls them (a pull subscription). Each registration is a Pub/Sub subscription on the topic platform.external.v1, filtered to the Organization and the event types chosen; Google retries, backs off and dead-letters, so there is no delivery worker and no shared secret. It is one API, with its own contract and its own version.
5.4.2.5.1 Versions¶
| Version | Status | Prod URL | Contract |
|---|---|---|---|
v1 |
Proposed | https://access.moonitoring.com/webhooks/v1 |
webhooks/v1/openapi.yaml |
The data model has no entities for this domain yet; its schemas are part of the proposal. No entity in the data model: WebhookSubscription and FailedDelivery are new, and each subscription is a Pub/Sub subscription on platform.external.v1 (D9). The capability is access.webhooks.manage (req 1002.26).
Pub/Sub supplies transport, retries and best-effort dead-letter forwarding. The 24-hour pause/notification policy and the 30-day queryable failure history still require platform monitoring, subscription management and an application read/redelivery path. They must be implemented and verified before this API is released; the absence of a custom delivery worker does not remove these responsibilities.
5.4.2.5.2 Operations¶
Every operation names who calls it and the capability it checks (x-moonitoring-audience, x-moonitoring-capability in the contract); every capability is in the catalog of the data model (req 1002, 1006). Lists are paged by cursor, writes that create something carry an Idempotency-Key, errors are Problem Details.
| Operation | Request | Who | Capability |
|---|---|---|---|
| List subscribable event types | GET /event-types |
Organization users, staff or clients | none: any member of the Organization |
| List subscriptions | GET /subscriptions |
Organization users | access.webhooks.manage |
| Create a subscription | POST /subscriptions |
Organization users | access.webhooks.manage |
| Read a subscription | GET /subscriptions/{subscription_id} |
Organization users | access.webhooks.manage |
| Update a subscription | PATCH /subscriptions/{subscription_id} |
Organization users | access.webhooks.manage |
| Delete a subscription | DELETE /subscriptions/{subscription_id} |
Organization users | access.webhooks.manage |
| Send a test event | POST /subscriptions/{subscription_id}/test |
Organization users | access.webhooks.manage |
| Resume a paused subscription | POST /subscriptions/{subscription_id}/resume |
Organization users | access.webhooks.manage |
| List failed deliveries | GET /subscriptions/{subscription_id}/failures |
Organization users | access.webhooks.manage |
| Deliver a failed event again | POST /failures/{failure_id}/redeliver |
Organization users | access.webhooks.manage |
5.4.2.5.3 Contract v1¶
Proposed version
v1 is a proposal for review: its endpoints, errors and capabilities were designed from the requirements and the flows and are not confirmed. It leaves proposal with its first release; from then on it changes only as described in Every API Is Versioned.