Webhook events

Two directions

Rendering diagram…

Inbound (external → platform)

Remote systems POST to combo agent; signature verification routes into Event Triggers / sessions.

Envelope

POST /v1/webhook/{channel}
Content-Type: application/json
X-Combo-Signature: sha256=<hmac>
X-Combo-Timestamp: 1699999999
X-Combo-Event-Id: <unique-id>
 
{ ...channel-specific payload... }

Signature verification

HMAC-SHA256 over timestamp + "." + body using the secret from Integrations → Webhooks.

import hmac
import hashlib
 
def verify(body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    payload = timestamp.encode() + b"." + body
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Supported inbound channels

Channel	Path	Purpose
Feishu events	`/v1/webhook/lark`	Messages / approvals / calendar
WeCom events	`/v1/webhook/wecom`	Messages / directory
Gerrit hook	`/v1/webhook/gerrit`	`patchset-created`, `change-merged`, …
GitLab webhook	`/v1/webhook/gitlab`	Push / MR / pipeline
GitHub webhook	`/v1/webhook/github`	Push / PR / issues
Gitee webhook	`/v1/webhook/gitee`	GitHub-compatible payload
Generic	`/v1/webhook/generic/{trigger_id}`	Custom triggers

Outbound (platform → customer)

Push internal events to customer endpoints.

POST /v1/webhook/subscriptions
Content-Type: application/json
 
{
  "url": "https://client.example.com/combo-callback",
  "events": ["session.finished", "tool.called"],
  "secret": "your-shared-secret"
}

Event catalog

Event	When	Key payload fields
`session.created`	Session spins up	`session_id`, `tenant_id`, `user_id`
`session.finished`	Agent completes	`session_id`, `cost`, `artifacts`
`session.archived`	Session archived	`session_id`
`tool.called`	Tool invoked	`tool_name`, `session_id`, `args_hash`
`tool.error`	Tool failure	`tool_name`, `error`, `session_id`
`agent.step`	Verbose step tracing	`action`, `confidence`, `session_id`
`review.completed`	Code review wraps	`pr_url`, `report_url`, `issues_found`
`import.completed`	Requirement/bug ingest done	`source`, `count`, `errors`
`cost.threshold_exceeded`	Budget breached	`tenant_id`, `period`, `amount`

Payload example

{
  "event": "review.completed",
  "event_id": "evt_abc123",
  "timestamp": "2026-04-23T10:15:00Z",
  "tenant_id": "t_corp_a",
  "data": {
    "session_id": "sess_xyz",
    "pr_url": "https://gerrit.../c/12345",
    "report_url": "https://combo.../sessions/sess_xyz/report",
    "issues_found": {
      "critical": 2,
      "warning": 5,
      "info": 12
    },
    "cost": { "tokens": 8320, "duration_ms": 45000 }
  }
}

Retry policy

Attempt	Backoff
1	Immediate
2	30 s
3	2 min
4	10 min
5	1 h

Consumers must answer HTTP 2xx within ~2 s; failures roll into a dead-letter queue manageable in the console.

Event triggers bridge inbound → automation

YAML sketch:

trigger:
  source: gerrit
  match:
    event: patchset-created
    project_regex: "^platform/.*"
  action:
    agent_id: "code-review-agent"
    session_template: "code-review-session"
    inputs:
      pr_url: "{{ event.change.url }}"
      change_id: "{{ event.change.number }}"

FAQ

Q: Signature failures on inbound hooks? A: Rotate secrets deliberately; timestamps must be ±5 min; ensure proxies don’t mutate bodies.

Q: Consumers time out sporadically? A: Return 200 immediately, enqueue asynchronous processing—never block webhook threads.

Q: Replay historic events? A: Console → Integrations → Webhooks → Historical replay filtered by timeframe.

Webhook events

On this page