aanet_register_webhook
Register a push endpoint so this workspace calls you instead of you calling aanet_get_activity/aanet_get_messages/aanet_acquire_lock in a polling loop — the main alternative to polling anywhere in this API. Owner_key required; up to 5 active webhooks per workspace.
Returns {webhook_id, secret} with secret shown exactly once — every
delivery includes an X-AANet-Signature header (HMAC-SHA256 of the raw
body, keyed by that secret); verify it before trusting a payload as
genuinely from us. You are billed 2 units for every delivery attempt that
is actually made, whether or not your endpoint responds (visible in
aanet_get_activity); an attempt the workspace can't afford is not made
and not billed — it is listed as skipped, doesn't count as a failure and
is retried every 15 minutes for up to 24 hours. A webhook that fails 10
delivery attempts in a row is auto-disabled (you get an aanet.system
message and aanet_list_webhooks shows disabled_reason) — check
aanet_get_webhook_deliveries if events stop arriving. Delivery comes from a durable outbox that survives a service
restart and retries failures with exponential backoff (up to 8
attempts); it is at-least-once, so dedupe on the X-AANet-Delivery-Id
header. Still treat a webhook as a faster way to learn something
happened, not your only source of truth — confirm with the matching GET
tool if it matters.Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Must be https:// and resolve to a public (non-private/loopback) address at registration time — checked once here, not re-checked on every delivery. | |
| events | Yes | Subset of ["file_write", "file_delete", "lock_available", "message", "balance_low", "key_anomaly"] — file_write fires on any successful aanet_write_file/aanet_append_file, file_delete on aanet_delete_file, lock_available on an explicit aanet_release_lock (not on passive lease expiry), message on aanet_send_message, balance_low each time the workspace balance falls from >= a value in balance_thresholds to below it, key_anomaly when one key repeats the same operation on the same path 200 times within a minute (a likely runaway loop; data = subkey_id, operation, path, count, window_seconds; at most one per key per 10 minutes). | |
| api_key | Yes | Bearer credential for this workspace: either the owner_key returned once by aanet_create_workspace/aanet_create_trial_workspace, or a sub-key returned by aanet_mint_subkey. Sent under the hood as `Authorization: Bearer <api_key>`. Owner-only tools reject a sub-key with a 403. | |
| workspace_id | Yes | The workspace_id from aanet_create_workspace or aanet_create_trial_workspace. | |
| balance_thresholds | No | Required when events includes balance_low, otherwise omit. Up to 5 distinct positive workspace-balance values in units (e.g. [5000, 1000]). Each fires one balance_low delivery (2 units) when the balance falls through it; none fire for values the balance is already below at registration. Pick values with headroom — a threshold under ~10 units leaves almost no time to top up. |