subscribe_audit

Subscribe to an org's audit log

act entity tenant-private since 2026-10-01

Subscribes an email digest or a Slack incoming webhook to an org's audit log, or changes or disables that subscription. alerts_only narrows it to the admin activity alerts: a new admin, an SSO change, an API key created. A digest is sent hourly or daily with counts only; Slack gets one message per event with ids and names only. One destination is one subscription, so subscribing it again changes it; enabled false turns it off. The Slack webhook URL is never returned.

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: natural
emits: audit.subscribed
MCP tool: subscribe_audit
decision_set: approve, reject, edit, request_info
REST: POST https://api.containertradehq.com/v1/cap/subscribe_audit

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org whose audit log is subscribed to.
channel	one_of	required	one of digest, slack digest: an email summary through Resend. slack: a Slack incoming webhook.
destination	text	required	3 to 512 characters For digest, the one email address. For slack, the incoming webhook URL, https://hooks.slack.com/services/...
alerts_only	boolean	optional	Only the admin activity alerts (default false: every audit event of the org).
cadence	one_of	optional	one of hourly, daily Digest only: hourly (the default) or daily.
enabled	boolean	optional	false turns the subscription off (default true).

Response

subscription_id · string · The subscription's id.
org_id · string · The org.
channel · string · digest or slack.
destination · value · The email address for a digest; for Slack, only the host, because the webhook URL is a credential.
alerts_only · boolean · Whether only admin activity alerts are sent.
cadence · stringnull · A digest's cadence; null for Slack, which posts each event as it is recorded.
enabled · boolean · Whether it sends.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "string",
      "description": "The subscription's id.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org.",
      "x-data-class": "operational"
    },
    "channel": {
      "type": "string",
      "enum": [
        "digest",
        "slack"
      ],
      "description": "digest or slack.",
      "x-data-class": "operational"
    },
    "destination": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The email address for a digest; for Slack, only the host, because the webhook URL is a credential.",
      "x-data-class": "personal"
    },
    "alerts_only": {
      "type": "boolean",
      "description": "Whether only admin activity alerts are sent.",
      "x-data-class": "operational"
    },
    "cadence": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "hourly",
        "daily",
        null
      ],
      "description": "A digest's cadence; null for Slack, which posts each event as it is recorded.",
      "x-data-class": "operational"
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether it sends.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "subscription_id",
    "org_id",
    "channel",
    "destination",
    "alerts_only",
    "cadence",
    "enabled"
  ],
  "additionalProperties": false
}

Refusals

cadence_is_digest_only · 422 · a cadence was sent for a Slack subscription; only a digest has one
invalid_slack_webhook · 422 · the destination is not a Slack incoming webhook URL
invalid_email · 422 · the destination is not an email address a digest can be sent to

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileD5

APIF

MCPF*

VoiceD5

PushF

OneBoxN

OutboundN

Mobile: degraded: composition
MCP: approval required
Voice: degraded: composition
OneBox: no document originates a subscription
Outbound: crosses to no counterparty

Events

audit.subscribed audit_only

export_audit_events, list_audit_events, set_my_notification, set_notification_policy

get a test key

curl https://api.containertradehq.com/v1/cap/subscribe_audit \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_id>","channel":"digest","destination":"<destination>"}'

import { TradeHQ } from '@containertradehq/sdk';

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.subscribeAudit({
  "org_id": "<org_id>",
  "channel": "digest",
  "destination": "<destination>"
});

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.subscribe_audit({
    "org_id": "<org_id>",
    "channel": "digest",
    "destination": "<destination>",
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "subscribe_audit",
    "arguments": {
      "org_id": "<org_id>",
      "channel": "digest",
      "destination": "<destination>"
    }
  }
}

MCP

subscribe_audit · readOnlyHint false · approval required

“Call subscribe_audit”