Hanzo AIDocs
Sign inAPI key

Create 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 → · All API references → · Get started →

Addresshttps://api.hanzo.ai/v1/webhook
MethodPOST
Operationpost_webhook
AuthAuthorization: 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).

FieldInTypeRequiredDescription
descriptionbodystring—Description is a free-text label for the console.
eventsbodystring[]—Events are NATS subject patterns to subscribe to (e.g. "commerce.order.>").
statusbodystring—Status is "active" or "disabled".
urlbodystring—URL is the https:// address each matching event is POSTed to.

Response

StatusBodyMeaning
201webhook.Endpointcreated
defaultproblem-detailsrefused

201 body — 11 fields.

FieldInTypeAlwaysDescription
createdbodystring—CreatedAt is when the endpoint was registered, RFC3339 in UTC — stored in that spelling because it sorts as a string.
deliveries7dbodyinteger (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.
descriptionbodystring—Description is the operator's own label for the endpoint.
eventsbodystring[]—Events are the subject patterns this endpoint subscribes to ("commerce.order.>").
failures7dbodyinteger (int64)—Failures7d is how many of those settled as failed — the subscriber never accepted it and no further attempt will be made.
idbodystring—ID is the endpoint's handle, server-minted and stable for its life.
orgbodystring—Org is the tenant that owns the endpoint, taken from the validated principal rather than from any request field.
secretbodystring—Secret is the HMAC-SHA256 signing key a subscriber recomputes the signature with.
statusbodystring—Status is "active" or "disabled" — nothing else is accepted.
updatedbodystring—UpdatedAt is when its url, events, status or description last changed.
urlbodystring—URL is where the POST goes.

Failure carries the platform error shape — see Errors.

Examples

hanzo webhook 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 := 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
}
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?;
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();
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 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:

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

Was this page useful?
PreviousTest webhookNextReplace webhook