Create and test a webhook

Create a webhook that passes support tickets to a project agent, then test its filter and target through the API. You need an existing agent and an API credential with permission to manage and run project webhooks. The example uses triage-agent in support-assistant.

1. Create the webhook

Create the definition with POST /projects/{project_reference}/webhooks:

create-webhook.sh

curl -X POST https://api.veryfront.com/projects/support-assistant/webhooks \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage new tickets",
    "target": {"kind":"agent","id":"triage-agent","conversation_mode":"none"},
    "prompt_template": "Classify this support ticket and suggest the next action: {{payload.ticket.description}}",
    "event_filter": {
      "mode": "all",
      "conditions": [{"path":"type","operator":"equals","value":"ticket.created"}]
    }
  }'

Save webhook.id as WEBHOOK_DEFINITION_ID. The response also returns webhook_secret once; retain it for sender configuration.

2. Test the webhook

Invoke the definition with POST /projects/{project_reference}/webhooks/{webhook_definition_id}/run:

test-webhook.sh

curl -X POST "https://api.veryfront.com/projects/support-assistant/webhooks/$WEBHOOK_DEFINITION_ID/run" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"type":"ticket.created","ticket":{"id":"1001","description":"I need help updating my subscription."}}}'

This authenticated invocation applies the definition’s event filter and target. Each call creates a new event, so inspect the returned run before repeating it.

Verify the result

Inspect the returned status. When canonical_run_id is present, read that run through GET /runs/{run_id} and check the agent’s result. A payload that does not match the filter is stored without starting a run. Check the event type and filter before treating an ignored delivery as a runtime failure.

Conversation behavior

conversation_mode: "none" runs the agent without a conversation. Use create_new for a new conversation, including agents that delegate with invoke_agent. To continue a conversation, use existing and supply conversation_id. Other target kinds and their requirements are listed in the webhook reference.

API references

Interface	Operations
REST	Create a webhook · Run a webhook · Read a run
GraphQL	Create a webhook
MCP	Create a webhook · Run a webhook

Get started

APIs

REST API

GraphQL API

MCP API

Create and test a webhook

1. Create the webhook

2. Test the webhook

Verify the result

Conversation behavior

API references

​1. Create the webhook

​2. Test the webhook

​Verify the result

​Conversation behavior

​API references

1. Create the webhook

2. Test the webhook

Verify the result

Conversation behavior

API references