Replaces the editable fields of one of the caller org's endpoints — url,…
Replaces the editable fields of one of the caller org's endpoints — url, events, status and description — and answers the stored row with its secret…
PUT /v1/webhook/{id}
| Address | https://api.hanzo.ai/v1/webhook/{id} |
| Method | PUT |
| Operation | put_webhook_by_id |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Replaces the editable fields of one of the caller org's endpoints — url, events, status and description — and answers the stored row with its secret redacted. It is a full replace, not a patch: an omitted field is written as its empty value, and an omitted or empty events list resubscribes the endpoint to EVERY event. The signing secret and the creation time are immutable here; rotate the secret with POST /v1/webhook/{id}/secret.
Request
5 fields, body application/json (required).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | |
description | body | string | — | Description is a free-text label for the console. |
events | body | string[] | — | Events are NATS subject patterns to subscribe to. |
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 |
|---|---|---|
200 | Endpoint | ok |
200 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 set <id>import { Configuration, WebhookApi } from 'hanzoai';
const api = new WebhookApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.putWebhookById({ id: 'id', 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).put_webhook_by_id(id='id', description="<description>", events=["<events>"])cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.WebhookAPI.PutWebhookById(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::put_webhook_by_id(&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).putWebhookById();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 PUT https://api.hanzo.ai/v1/webhook/<id> \
-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"
}
}
}'How is this guide?