Mutation
createWebhookSubscription
Create an outbound-webhook subscription. Returns the signing secret exactly once.
Arguments
Object, input and enum types open in place — use + to reveal their fields. A type that is already open above the row stops at a ↻ circular marker, and anything nested past the depth limit links out to its own page instead.
- input CreateWebhookSubscriptionInput! required
- Mutation input.
- eventTypes [String!] default ["content_view.item_added"]
- Event types to subscribe to. Defaults to [content_view.item_added], the only subscribable type in v1.
- metadata JSON default {}
- Opaque JSON object echoed back verbatim as subscription_metadata on every delivery envelope. Use it to carry your own reference IDs. Capped at 4 KB serialized. Pass an object, not a stringified blob.
- name String! required
- Display name for the subscription.
- url String! required
- HTTPS endpoint deliveries are POSTed to. Validated against SSRF ranges.
- viewIds [ID!] default []
- Content View (FilterPreset) UUIDs whose newly matching items trigger deliveries. Required when any subscribed event type is view-scoped, which is every subscribable type in v1: pass at least one UUID, each owned by the workspace. Must be omitted for non-view event types (none are subscribable yet). v1 ships one event type (content_view.item_added), so express each condition you want to be notified about (verified mentions, usage-rights approved, high EMV, and so on) as a Content View whose filters encode that condition, then point viewIds at it.
Returns
- secret String
- The plaintext signing secret (whsec_-prefixed). Returned only here and from rotateWebhookSubscriptionSecret, and never shown again, so store it immediately. The whsec_ prefix is part of the HMAC key; do not strip it when verifying X-Archive-Signature.
- userErrors [UserError!]!
- List of user-facing validation errors. Empty on success.
- field [String!]
- Path to the input field that caused the error.
- message String!
- The error message.
- webhookSubscription WebhookSubscription
- The newly created subscription. Null on failure.
- consecutiveFailures Int!
- Consecutive failed deliveries since the last success. Resets to 0 on the next successful delivery.
- createdAt DateTimeWithZone!
- When the subscription was created.
- disabledAt DateTimeWithZone
- When the subscription was disabled by failures. Null while active/paused.
- eventTypes [String!]!
- Event types this subscription matches (e.g. content_view.item_added).
- id ID!
- Unique identifier of the subscription.
- lastSuccessAt DateTimeWithZone
- When the most recent successful delivery occurred. Null if none yet.
- metadata JSON!
- Opaque JSON object echoed back verbatim as subscription_metadata on every delivery envelope.
- name String!
- Display name of the subscription.
- status WebhookSubscriptionStatus!
- Current lifecycle status. ACTIVE delivers; DISABLED_BY_USER is a manual pause; DISABLED_BY_FAILURES is a system auto-disable triggered by a 410 Gone, 20 consecutive exhausted deliveries, or 3 days of continuous failure; re-enable with enableWebhookSubscription.
- ACTIVE
- The subscription is active and receives matching events.
- DISABLED_BY_FAILURES
- The subscription was disabled by the system after sustained delivery failures (a 410 Gone, 20 consecutive exhausted deliveries, or 3 days of continuous failure). Re-enable it with the enableWebhookSubscription mutation.
- DISABLED_BY_USER
- The subscription was paused by the workspace and delivers nothing until re-enabled.
- updatedAt DateTimeWithZone!
- When the subscription was last updated.
- url String!
- HTTPS endpoint deliveries are POSTed to.
- viewIds [ID!]!
- Content View (FilterPreset) UUIDs whose newly matching items trigger deliveries.