Registers a new webhook subscription for the caller's org and answers 201 with…

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 → · All API references → · Six flows, four surfaces →


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.>"). An empty or omitted list means EVERY event on the platform bus.
`status`	body	string	—	Status is "active" or "disabled". Empty defaults to active.
`url`	body	string	—	URL is the https:// address each matching event is POSTed to.

Response

Status	Body	Meaning
`201`	Endpoint	created

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	—	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…
`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	—	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.

Examples

hanzo webhooks create

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>"] });

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>"])

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

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

use hanzo_cloud::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?;

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

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

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

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

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>"
       ]
     }'

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

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 · All Hanzo APIs · Interactive reference

Registers a new webhook subscription for the caller's org and answers 201 with…

Request

Response

Examples

On this page