webhooks

Mirrors src/proxy/webhooks.ts.

Pass 11 landed the pure substrate. Pass 12 added the read path. Pass 13 adds the three webhook subscription mutations (webhookSubscriptionCreate / Update / Delete) plus a helper for top-level GraphQL argument validation.

What’s here:

endpoint_from_uri / uri_from_endpoint / webhook_subscription_uri (URI ↔ endpoint variant marshaling)
webhook_subscription_legacy_id (trailing-segment GID pull)
matches_webhook_term / filter_webhook_subscriptions_by_query
filter_webhook_subscriptions_by_field_arguments (format / uri / topics filters from the Admin GraphQL field args)
sort_webhook_subscriptions_for_connection (CREATED_AT / UPDATED_AT / TOPIC / ID, with stable tiebreak by id)
handle_webhook_subscription_query (root-field dispatch), process (full envelope), is_webhook_subscription_query_root (dispatcher predicate)
process_mutation plus the three mutation handlers (handle_webhook_subscription_create / _update / _delete) and the AST-level validate_required_field_arguments helper. When any mutation produces top-level errors, process_mutation returns a {"errors": [...]} envelope instead of {"data": {...}}.

Types

MutationOutcome

Outcome of a webhook-subscription mutation. Mirrors the saved-search outcome shape: a JSON envelope ({"data": ...} or {"errors": ...}), the updated store and identity registry, and the staged GIDs.

pub type MutationOutcome {
  MutationOutcome(
    data: json.Json,
    store: store.Store,
    identity: synthetic_identity.SyntheticIdentityRegistry,
    staged_resource_ids: List(String),
    log_drafts: List(mutation_helpers.LogDraft),
  )
}

Constructors

MutationOutcome(
  data: json.Json,
  store: store.Store,
  identity: synthetic_identity.SyntheticIdentityRegistry,
  staged_resource_ids: List(String),
  log_drafts: List(mutation_helpers.LogDraft),
)

UserError

User-error payload emitted on validation failure. Mirrors the WebhookSubscriptionUserError shape in TS.

pub type UserError {
  UserError(field: List(String), message: String)
}

Constructors

UserError(field: List(String), message: String)

WebhookSubscriptionSortKey

The four sort keys the connection accepts. Mirrors the TS string switch — anything unrecognised falls through to Id.

pub type WebhookSubscriptionSortKey {
  CreatedAtKey
  UpdatedAtKey
  TopicKey
  IdKey
}

Constructors

```
CreatedAtKey
```
```
UpdatedAtKey
```
```
TopicKey
```
```
IdKey
```

WebhooksError

Errors specific to the webhooks handler. Currently just surfaces upstream parse errors.

pub type WebhooksError {
  ParseFailed(root_field.RootFieldError)
}

Constructors

```
ParseFailed(root_field.RootFieldError)
```

Values

endpoint_from_uri

pub fn endpoint_from_uri(
  uri: String,
) -> types.WebhookSubscriptionEndpoint

Mirrors endpointFromUri. Three URI shapes:

pubsub://<project>:<topic> → PubSub endpoint (split on first :; if no :, the whole tail goes to pub_sub_project and topic is empty)
arn:aws:events:... → EventBridge endpoint, ARN copied verbatim
anything else → HTTP endpoint with the URI as the callback URL

filter_webhook_subscriptions_by_field_arguments

pub fn filter_webhook_subscriptions_by_field_arguments(
  records: List(types.WebhookSubscriptionRecord),
  format: option.Option(String),
  uri: option.Option(String),
  topics: List(String),
) -> List(types.WebhookSubscriptionRecord)

Mirrors filterWebhookSubscriptionsByFieldArguments. Each filter is optional: missing or empty filters pass through.

filter_webhook_subscriptions_by_query

pub fn filter_webhook_subscriptions_by_query(
  records: List(types.WebhookSubscriptionRecord),
  raw_query: option.Option(String),
) -> List(types.WebhookSubscriptionRecord)

Mirrors filterWebhookSubscriptionsByQuery. Empty / whitespace-only queries leave the list unchanged. Otherwise the query is parsed with AND ignored as a connector keyword and AND-semantics applied across remaining terms.

handle_webhook_subscription_query

pub fn handle_webhook_subscription_query(
  store: store.Store,
  document: String,
  variables: dict.Dict(String, root_field.ResolvedValue),
) -> Result(json.Json, WebhooksError)

Process a webhooks query document and return a JSON data envelope. Mirrors handleWebhookSubscriptionQuery. The Store argument supplies effective (base + staged) records.

is_webhook_subscription_mutation_root

pub fn is_webhook_subscription_mutation_root(
  name: String,
) -> Bool

Predicate matching isWebhookSubscriptionMutationRoot. Three top-level mutations the TS handler dispatches.

is_webhook_subscription_query_root

pub fn is_webhook_subscription_query_root(name: String) -> Bool

Predicate matching isWebhookSubscriptionQueryRoot. Useful for the dispatcher when checking whether to delegate.

matches_webhook_term

pub fn matches_webhook_term(
  record: types.WebhookSubscriptionRecord,
  term: search_query_parser.SearchQueryTerm,
) -> Bool

Mirrors matchesWebhookTerm (without the negation flip — that’s applied by matches_search_query_term so this function is a pure positive-term matcher).

parse_sort_key

pub fn parse_sort_key(raw: String) -> WebhookSubscriptionSortKey

process

pub fn process(
  store: store.Store,
  document: String,
  variables: dict.Dict(String, root_field.ResolvedValue),
) -> Result(json.Json, WebhooksError)

Convenience: parse + handle + wrap, for the dispatcher.

process_mutation

pub fn process_mutation(
  store: store.Store,
  identity: synthetic_identity.SyntheticIdentityRegistry,
  request_path: String,
  document: String,
  variables: dict.Dict(String, root_field.ResolvedValue),
) -> Result(MutationOutcome, WebhooksError)

Process a webhook-subscription mutation document and return a MutationOutcome. Mirrors handleWebhookSubscriptionMutation. Top-level argument-validation errors short-circuit the whole envelope to {"errors": [...]}; otherwise per-field payloads are collected into {"data": {...}}.

sort_webhook_subscriptions_for_connection

pub fn sort_webhook_subscriptions_for_connection(
  records: List(types.WebhookSubscriptionRecord),
  sort_key: WebhookSubscriptionSortKey,
  reverse: Bool,
) -> List(types.WebhookSubscriptionRecord)

Mirrors sortWebhookSubscriptionsForConnection. Stable tiebreak on the GID’s numeric tail keeps order deterministic when the primary key has duplicates (e.g. two records sharing a topic).

uri_from_endpoint

pub fn uri_from_endpoint(
  endpoint: option.Option(types.WebhookSubscriptionEndpoint),
) -> option.Option(String)

Mirrors uriFromEndpoint. Returns None when the endpoint doesn’t carry the field its kind needs (e.g. PubSub with a missing project or topic).

webhook_subscription_legacy_id

pub fn webhook_subscription_legacy_id(
  record: types.WebhookSubscriptionRecord,
) -> String

Mirrors webhookSubscriptionLegacyId. The legacy id is the trailing path segment of the GID; if there’s no /, the whole id is returned.

webhook_subscription_uri

pub fn webhook_subscription_uri(
  record: types.WebhookSubscriptionRecord,
) -> option.Option(String)

Mirrors webhookSubscriptionUri. Prefers the explicit uri field; falls back to deriving one from the endpoint.

wrap_data

pub fn wrap_data(data: json.Json) -> json.Json

Wrap a successful webhooks response in the standard GraphQL envelope.