Trigger work from a webhook

Start an agent, task or workflow when an external system sends a matching JSON event.

Steps

  1. Create a webhook for the project.
  2. Choose an agent, task or workflow target.
  3. Configure the source system with the webhook URL and secret.
  4. Add a filter when only some events should run.
  5. Test the webhook and inspect the target run.

Try it with REST

Create a webhook that runs an agent for opened pull requests:

POST /projects/{project_reference}/webhooks

bash
curl -X POST https://api.veryfront.com/projects/support-assistant/webhooks \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review new pull requests",
    "target": {
      "kind": "agent",
      "id": "triage-agent"
    },
    "prompt_template": "Review pull request {{payload.pull_request.html_url}}.",
    "event_filter": {
      "mode": "all",
      "conditions": [
        {
          "path": "action",
          "operator": "equals",
          "value": "opened"
        }
      ]
    }
  }'

Verify

Send a matching test event from the source system. Open its delivery record, follow the target run and inspect its result.

How webhooks work

StepWhat happens
1An external system sends a JSON payload to the webhook URL.
2Veryfront checks the webhook secret and enabled state.
3Veryfront applies the optional filter.
4Matching events render the prompt template.
5Veryfront starts the target agent, task, or workflow run.

Ignored events are stored without creating a run. Agent targets run without a conversation by default. Set conversation_mode to create_new or existing when the run needs a conversation. The existing mode also requires conversation_id. Conversation-backed targets require project.conversations.write.

Target kinds

Each webhook has one target.

TargetUse it when
agentAn AI agent reasons over the event.
taskA background task runs.
workflowA multi-step process runs.
eventStore the event without starting a run. Use target ID event and omit prompt_template.

Prompt template

For agent, task and workflow targets, the prompt template describes what to do with the event.

text
Review pull request {{payload.pull_request.html_url}}.
Action: {{payload.action}}
Title: {{payload.pull_request.title}}

Keep templates explicit about the expected output and acceptance criteria.

Filter

A filter decides whether an incoming event starts a run.

json
{
  "mode": "all",
  "conditions": [
    { "path": "action", "operator": "equals", "value": "opened" }
  ]
}
FieldMeaning
modeall requires every condition. any accepts one matching condition.
pathDot path to a JSON field in the payload.
operatorComparison to run, such as equals, not_equals, in, exists, or contains.
valueExpected value for the comparison.

Operate webhooks

  • Confirm the source system uses the current webhook URL and secret.
  • Check accepted, ignored, and failed deliveries.
  • Open the target run from an accepted event.
  • Replay failed events after fixing the webhook, target, or source configuration.

API reference