# Create webhook

URL: https://docs.hanzo.ai/docs/openapi/webhook/post-webhook

> Registers a new webhook subscription for the caller's org and answers 201 with the endpoint INCLUDING its freshly minted signing secret.

`POST /v1/webhook`

> [Webhook →](https://docs.hanzo.ai/docs/openapi/webhook) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                        |
| ------------- | -------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/webhook`      |
| **Method**    | `POST`                                 |
| **Operation** | `post_webhook`                         |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY` |

Registers a new webhook subscription for the caller's org and
answers 201 with the endpoint INCLUDING its freshly minted signing secret.
This is one of only two responses that ever carry that secret (the other is
rotate) — store it now, because no later read returns it. The org is stamped by
the server from the validated principal, so a body can never register an
endpoint in another tenant.

## Request

4 fields, body `application/json` (required).

| Field         | In   | Type      | Required | Description                                                                 |
| ------------- | ---- | --------- | -------- | --------------------------------------------------------------------------- |
| `description` | body | string    | —        | Description is a free-text label for the console.                           |
| `events`      | body | string\[] | —        | Events are NATS subject patterns to subscribe to (e.g. "commerce.order.>"). |
| `status`      | body | string    | —        | Status is "active" or "disabled".                                           |
| `url`         | body | string    | —        | URL is the https\:// address each matching event is POSTed to.              |

## Response

| Status    | Body             | Meaning |
| --------- | ---------------- | ------- |
| `201`     | webhook.Endpoint | created |
| `default` | problem-details  | refused |

`201` body — 11 fields.

| Field          | In   | Type            | Always | Description                                                                                                                                                        |
| -------------- | ---- | --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `created`      | body | string          | —      | CreatedAt is when the endpoint was registered, RFC3339 in UTC — stored in that spelling because it sorts as a string.                                              |
| `deliveries7d` | body | integer (int64) | —      | Deliveries7d is how many deliveries SETTLED in the trailing 7 days — the attempts that ended ok or failed, so a delivery still retrying is in neither counter yet. |
| `description`  | body | string          | —      | Description is the operator's own label for the endpoint.                                                                                                          |
| `events`       | body | string\[]       | —      | Events are the subject patterns this endpoint subscribes to ("commerce.order.>").                                                                                  |
| `failures7d`   | body | integer (int64) | —      | Failures7d is how many of those settled as failed — the subscriber never accepted it and no further attempt will be made.                                          |
| `id`           | body | string          | —      | ID is the endpoint's handle, server-minted and stable for its life.                                                                                                |
| `org`          | body | string          | —      | Org is the tenant that owns the endpoint, taken from the validated principal rather than from any request field.                                                   |
| `secret`       | body | string          | —      | Secret is the HMAC-SHA256 signing key a subscriber recomputes the signature with.                                                                                  |
| `status`       | body | string          | —      | Status is "active" or "disabled" — nothing else is accepted.                                                                                                       |
| `updated`      | body | string          | —      | UpdatedAt is when its url, events, status or description last changed.                                                                                             |
| `url`          | body | string          | —      | URL is where the POST goes.                                                                                                                                        |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo webhook create
```

**SDK**

**.ts**

```ts
import { Configuration, WebhookApi } from 'hanzoai';

const api = new WebhookApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postWebhook({ description: "<description>", events: ["<events>"] });
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import WebhookApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = WebhookApi(client).post_webhook(description="<description>", events=["<events>"])
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.WebhookAPI.PostWebhook(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, webhook_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = webhook_api::post_webhook(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.WebhookApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new WebhookApi(client).postWebhook();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/webhook \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "description": "<description>",
       "events": [
         "<events>"
       ]
     }'
```

**MCP**

MCP reaches **webhook** through the `webhook` tool, which names its 7 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_webhooks"
         }
       }
     }'
```

---

[Webhook API](https://docs.hanzo.ai/docs/openapi/webhook) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)