# createWebhookSubscription

Mutation

Create an outbound-webhook subscription. Returns the signing secret exactly once.

Available to agents as MCP tool `createWebhookSubscription` — see [Write tools](/api/v2/docs/mcp/write-tools#create-webhook-subscription).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `input` | [`CreateWebhookSubscriptionInput!`](/api/v2/docs/types/create-webhook-subscription-input) | Yes | — | Mutation input. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `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!]!`](/api/v2/docs/types/user-error) | List of user-facing validation errors. Empty on success. |
| `webhookSubscription` | [`WebhookSubscription`](/api/v2/docs/types/webhook-subscription) | The newly created subscription. Null on failure. |

## Examples

### Create a webhook subscription

Subscribe an HTTPS endpoint to new items landing in a content view. `secret` is the signing secret and is returned exactly once — store it now, no read ever re-exposes it.

```graphql
mutation CreateWebhookSubscriptionDefault($input: CreateWebhookSubscriptionInput!) {
  createWebhookSubscription(input: $input) {
    webhookSubscription {
      id
      name
      url
      eventTypes
      viewIds
      metadata
      status
    }
    secret
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "input": {
    "name": "Fulfilment webhook",
    "url": "https://hooks.northwind-botanicals.example/archive/new-content",
    "viewIds": [
      "eaa824b8-374f-5db8-bee2-51dfd8c3776c"
    ],
    "eventTypes": [
      "content_view.item_added"
    ],
    "metadata": {
      "team": "fulfilment"
    }
  }
}
```

Response — HTTP 200:

```json
{
  "data": {
    "createWebhookSubscription": {
      "webhookSubscription": {
        "id": "b24c9093-72a3-504d-b97c-cb023efca979",
        "name": "Fulfilment webhook",
        "url": "https://hooks.northwind-botanicals.example/archive/new-content",
        "eventTypes": [
          "content_view.item_added"
        ],
        "viewIds": [
          "eaa824b8-374f-5db8-bee2-51dfd8c3776c"
        ],
        "metadata": {
          "team": "fulfilment"
        },
        "status": "ACTIVE"
      },
      "secret": "whsec_EXAMPLE_SECRET_SHOWN_ONCE_DO_NOT_USE",
      "userErrors": []
    }
  }
}
```