Skip to content

6.2.2.19 WebhookSubscription

6.2.2.19.1 Purpose

How an Organization receives events outside the platform: a Pub/Sub subscription on platform.external.v1, filtered by the Organization and the event types it chose, pushed to its HTTPS address with a Google-signed token or pulled by its own Google service account. access creates and changes the Pub/Sub subscription, and this row records it. A push address receives nothing until it answers a signed challenge, and the platform pauses a subscription whose deliveries have failed for 24 hours, keeping its events for seven days.

6.2.2.19.2 Questions it answers

  • Which events does this Organization receive outside, and where?
  • Is a push address verified, active, paused or disabled, and why?
  • Which Pub/Sub subscription delivers it?

6.2.2.19.3 Fields

Field Type Cardinality Description
id string (uuid) 1..1 Key.
organization Organization 1..1
kind enum 1..1 Values: push, pull.
url string 0..1 For push: a public HTTPS address with a valid certificate, never a private or Moonitoring address.
audience string 0..1 For push: the audience of the OIDC token Google signs for each delivery.
service_account string 0..1 For pull: the customer's Google service account, given the subscriber role on the subscription.
subscription_name string 1..1 Unique.
The Pub/Sub subscription access created. Filters cannot change, so new event types mean a new Pub/Sub subscription; the old one is deleted once its backlog is delivered, and its name stays in system_version.
event_types string 1..* Event types with their version, from the catalogs (CapabilityCatalog); a new version never reaches a subscription that did not choose it.
The Pub/Sub filter holds only the Organization, because a filter is limited to 256 characters: a message transform on the subscription drops the types not chosen. Isolation between Organizations stays in the filter; the transform only narrows an Organization's own events.
status enum 1..1 Values: pending_verification, active, paused, disabled. Default: pending_verification.
pending_verification: a push address that has not answered the challenge yet; a pull subscription is active at once.
paused: by the platform after 24 hours of failures, with the owner told; disabled: by the owner.
verified_at datetime 0..1
paused_reason string 0..1
created_by User 1..1
system_version SystemVersion 1..1
created_at datetime 1..1
updated_at datetime 1..1

6.2.2.19.4 Relationships

References

Referenced by

Uses types

SystemVersion

6.2.2.19.5 Rules & constraints

  • How an Organization receives events outside the platform, as interface decision D9 chose: a Pub/Sub subscription on platform.external.v1, filtered by the Organization and the event types it chose, either pushed to its HTTPS address or pulled by its own Google service account. access creates and changes the Pub/Sub subscription; this row is the record of it.
  • Verification: access POSTs a subscription.verification.v1 CloudEvent to the address, signed with the delivery service account's OIDC token and carrying a random challenge; the address must answer 200 with the same challenge within ten seconds, as Slack and Microsoft Graph do. Until then Pub/Sub delivers nothing to it.
  • Pause: the access sweeper pauses a push subscription when its deliveries have failed for 24 hours, that is FailedDeliveries (FailedDelivery) kept arriving and Cloud Monitoring counted no successful push in that time.
  • Pausing removes the push address from the Pub/Sub subscription, which keeps the events up to its retention of seven days; resuming verifies the address again and restores it.