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]. operation.completed (not view-scoped) fires once when a refetch_engagement or oneschema_creator_import operation finishes.
- 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. Must not be blank; at most 200 characters.
- url String! required
- HTTPS endpoint deliveries are POSTed to. Validated against SSRF ranges; at most 2048 characters.
- viewIds [ID!] default []
- Content View (FilterPreset) UUIDs whose newly matching items trigger deliveries. Required when any subscribed event type is view-scoped (content_view.item_added): pass at least one UUID, each owned by the workspace. Must be omitted or empty when only operation.completed is subscribed. Express each content 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 (content_view.item_added, operation.completed).
- 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.