Trigger work from a webhook

Use a webhook to start work from an external event. The webhook receives a JSON payload and starts an agent, job, or workflow.

Steps

Create a webhook for the project.
Choose one target: agent, job, or workflow.
Configure the source system with the webhook URL and secret.
Add a filter when only some events should run.
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

Terminal

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"
        }
      ]
    }
  }'

API surfaces

Surface	Start here
REST	Project Webhooks, Run Project Webhook
MCP	Create Project Webhook, Run Project Webhook

Verify

Send a test event from the source system. Open the webhook delivery and confirm it created a target run.

How webhooks work

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

Ignored events are stored without creating a run. Webhooks do not create conversations.

Target kinds

Each webhook has one target.

Target	Use it when
`agent`	An AI agent reasons over the event.
`job`	A background target runs.
`workflow`	A multi-step process runs.

Prompt template

The prompt template tells the target what to do with the event.

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.

{
  "mode": "all",
  "conditions": [
    { "path": "action", "operator": "equals", "value": "opened" }
  ]
}

Field	Meaning
`mode`	`all` requires every condition. `any` accepts one matching condition.
`path`	Dot path to a JSON field in the payload.
`operator`	Comparison to run, such as `equals`, `not_equals`, `in`, `exists`, or `contains`.
`value`	Expected 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

API	Start here
REST	Webhook definitions and webhook invocation.
MCP	Automation tools available to assistants.

Getting Started

Concepts

Conversations API

Guides

Integrations

API Reference

REST API

GraphQL API

MCP API

Trigger work from a webhook

Steps

Try it with REST

API surfaces

Verify

How webhooks work

Target kinds

Prompt template

Filter

Operate webhooks

API reference

​Steps

​Try it with REST

​API surfaces

​Verify

​How webhooks work

​Target kinds

​Prompt template

​Filter

​Operate webhooks

​API reference

Steps

Try it with REST

API surfaces

Verify

How webhooks work

Target kinds

Prompt template

Filter

Operate webhooks

API reference