Webhook integrations

Directions

Inbound webhook

URL pattern

POST https://<combo-agent>/v1/webhook/generic/{trigger_id}
Content-Type: application/json
X-Combo-Signature: sha256=<hmac>
X-Combo-Timestamp: <unix_seconds>

{ ...payload... }

{trigger_id} is emitted when admins create triggers.

Steps

1. Console → Event triggers → Create (generic_webhook)
2. Copy URL + secret
3. Register with remote systems needing automation
4. Map JSON payloads to Agent inputs (JSONPath supported)

YAML sample:

trigger:
  source: generic_webhook
  secret: "<generated>"
  match:
    jsonpath: "$.action"
    equals: "escalated"
  action:
    agent_id: "ticket-triage"
    inputs:
      ticket_id: "{{ payload.ticket.id }}"
      priority: "{{ payload.ticket.priority }}"
      customer: "{{ payload.ticket.customer }}"

Client signing example

import hmac, hashlib, time, requests, json
 
secret = "your-webhook-secret"
body = json.dumps({"action": "escalated", "ticket": {...}}).encode()
ts = str(int(time.time()))
sig = "sha256=" + hmac.new(secret.encode(), ts.encode()+b"."+body, hashlib.sha256).hexdigest()
 
requests.post(
    "https://<combo-agent>/v1/webhook/generic/<trigger_id>",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Combo-Signature": sig,
        "X-Combo-Timestamp": ts,
    },
)

Outbound webhook

Expose agent lifecycle events (session.finished, tool.called, …) to downstream HTTP listeners.

Setup

1. Console → Integrations → Webhook subscriptions → Create
2. Provide HTTPS URL + event checklist + signing secret (platform-supplied optional)
3. combo agent pings the endpoint; subscriber must ACK 2xx

Event catalogue (subset)

Full payload references: Webhook events.

Retries

Consumers must ACK within two seconds—hand heavy work asynchronously.

Security controls

Auditing

webhook_audit rows capture hashes of headers/payload/timing/retries for both inbound/outbound deliveries—queryable inside the governance console.

FAQ

Q: Signature rejects? A: Resync secrets, ensure raw body hashing, beware middleware re-encoding.

Q: Bursty outbound traffic? A: Avoid blanket tool.called subscriptions unless sinking into observability stacks.

Related docs

• Webhook reference tables
• Events concept
• Security