> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# webhooks create

> Create a webhook and capture its signing secret.

Create a webhook endpoint for the authenticated workspace. The response returns the signing secret exactly once — capture it now, because it can never be read again. Use the returned webhook id with [`clay routines runs start --webhook-id`](/cli/reference/routines-runs-start).

See the [webhooks overview](/cli/reference/webhooks) for the delivery payload shape and signature verification.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay webhooks create <url>
```

## Arguments

| Argument | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `url`    | HTTPS endpoint that will receive signed webhook deliveries. Required. |

## Output

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "wh_abc123",
  "url": "https://example.com/hooks/clay",
  "createdAt": "2026-06-16T17:50:00.000Z",
  "signingSecret": "whsec_..."
}
```

| Field           | Type   | Description                                                                                |
| --------------- | ------ | ------------------------------------------------------------------------------------------ |
| `id`            | string | Webhook id. Pass it to `--webhook-id`, `clay webhooks test`, or `clay webhooks delete`.    |
| `url`           | string | The endpoint that receives deliveries.                                                     |
| `createdAt`     | string | Creation timestamp.                                                                        |
| `signingSecret` | string | HMAC signing secret. **Returned exactly once** — store it now; it can never be read again. |

## Errors

| Code               | Exit | Notes                                            |
| ------------------ | ---- | ------------------------------------------------ |
| `validation_error` | 2    | `<url>` is not a valid URL.                      |
| `auth_forbidden`   | 3    | The API key lacks permission to manage webhooks. |
| `not_found`        | 6    | Webhooks are not enabled.                        |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay webhooks create https://example.com/hooks/clay
clay webhooks create https://example.com/hooks/clay | jq -r '.signingSecret'
```