WebhookConfig

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentline-cloud/json-schema/agentline-cloud-webhook-config-schema.json",
  "title": "WebhookConfig",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentline-cloud-openapi.json#/components/schemas/WebhookConfig",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2083,
      "minLength": 1,
      "format": "uri",
      "title": "Url",
      "description": "HTTPS URL that will receive this agent's events as signed JSON POSTs. Setting this replaces any existing webhook for the agent."
    },
    "agent_id": {
      "type": "string",
      "title": "Agent Id",
      "description": "ID (agt_...) of the agent whose events this webhook receives, from create_agent or list_agents. Each agent may have at most one webhook."
    },
    "secret": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Secret",
      "description": "Optional HMAC signing secret used to verify the signature header on delivered payloads. Omit to keep the current secret, or to auto-generate one for a new webhook."
    },
    "signature_header": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Signature Header",
      "description": "Header name for the HMAC-SHA256 signature of the raw body. Defaults to 'X-Webhook-Signature' (natively verified by Hermes, OpenClaw, and other agent platforms). Set to 'X-Hub-Signature-256' for GitHub-style verification, or any custom header name your platform expects. Omit to keep the existing value when updating."
    },
    "protocol": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "agentline-relay/1",
            "agentline-relay/2"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Protocol",
      "description": "Live relay protocol. 'agentline-relay/1' (default): one call.utterance POST per task, answer in the response body or via push. 'agentline-relay/2': typed POSTs (call.session.start, call.task.open, call.task.amend, call.task.cancel, call.session.end); answer only via POST /v1/calls/{call_id}/context and return 202 quickly. Omit to keep the existing value when updating."
    },
    "capabilities": {
      "anyOf": [
        {
          "$ref": "#/$defs/WebhookCapabilities"
        },
        {
          "type": "null"
        }
      ],
      "description": "Relay v2 capabilities. Omit to keep the existing value when updating."
    }
  },
  "type": "object",
  "required": [
    "url",
    "agent_id"
  ],
  "$defs": {
    "WebhookCapabilities": {
      "properties": {
        "supports_amend": {
          "type": "boolean",
          "title": "Supports Amend",
          "description": "Accepts call.task.amend POSTs: caller follow-ups on the open task, same turn_id, higher revision. When false, AgentLine holds follow-ups and sends them as one merged task after the current one settles.",
          "default": false
        },
        "supports_cancel": {
          "type": "boolean",
          "title": "Supports Cancel",
          "description": "Accepts call.task.cancel POSTs when the caller withdraws a task.",
          "default": false
        },
        "briefing": {
          "type": "boolean",
          "title": "Briefing",
          "description": "Accepts call.session.start at call start and pushes facts the caller is likely to need (disposition=facts, no turn_id).",
          "default": true
        },
        "streams_progress": {
          "type": "boolean",
          "title": "Streams Progress",
          "description": "Pushes partial/progress updates while it works.",
          "default": false
        }
      },
      "type": "object",
      "title": "WebhookCapabilities",
      "description": "What a webhook runtime supports on live relay calls (protocol v2)."
    }
  }
}