Webhooks

Send events from your application to trigger agent workflows.

Webhook Sources

A webhook source represents an external system that sends events to Agent Platform. Each source has its own authentication token.

Field	Type	Description
name*	string	Human-readable name for the source (e.g., 'Billing System')
token	string	Auto-generated authentication token (whk_ prefix)
description	string	Optional description of what events this source sends

Create one webhook source per external system. Each source gets its own token, so you can rotate or revoke tokens independently.

Sending Events

POST events to the webhook endpoint with your source token. The event_type field determines which trigger rules fire.

Send an event

curl -X POST https://agent-platform.example.com/webhooks/events \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: whk_abc123def456" \
  -d '{
    "event_type": "invoice.uploaded",
    "payload": {
      "invoice_id": "INV-2024-001",
      "filename": "invoice.pdf",
      "uploaded_by": "user@example.com",
      "file_url": "https://storage.example.com/invoices/inv-2024-001.pdf"
    }
  }'

Field	Type	Description
event_type*	string	Event type identifier. Must match a trigger's configured event_type.
payload*	object	Arbitrary JSON payload. Available to the agent via the trigger template.

Trigger Configuration

Triggers connect webhook events to agents. When an event matches a trigger's event_type and source, the trigger fires and sends a prompt to the agent.

trigger config

triggers:
  - name: "Invoice Upload Handler"
    type: webhook
    event_type: "invoice.uploaded"
    webhook_source: "billing-system"
    agent_id: "invoice-parser"
    auto_approve: true
    prompt_template: |
      A new invoice has been uploaded.

      Invoice ID: {{ .payload.invoice_id }}
      Filename: {{ .payload.filename }}
      Uploaded by: {{ .payload.uploaded_by }}
      File URL: {{ .payload.file_url }}

      Please process this invoice according to the SOP.

The prompt_template is a Go template that receives the webhook payload. Use {{ .payload.field_name }} to interpolate event data into the agent's prompt.

Event Deduplication

Agent Platform deduplicates webhook events using a hash of the event_type and payload. Identical events received within a 5-minute window are silently dropped.

If you need to send the same payload multiple times, include a unique identifier (like a timestamp or request ID) in the payload to differentiate the events.

Response Codes

Field	Type	Description
200	OK	Event accepted and dispatched to matching triggers
401	Unauthorized	Invalid or missing X-Webhook-Token
404	Not Found	No webhook source found for the provided token
409	Conflict	Duplicate event (already processed within dedup window)
422	Unprocessable	Missing required fields (event_type, payload)