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

​
Steps

  1. Create a webhook for the project.
  2. Choose one target: agent, job, or workflow.
  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
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

SurfaceStart here
RESTProject Webhooks, Run Project Webhook
MCPCreate 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

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, job, or workflow run.
Ignored events are stored without creating a run. Webhooks do not create conversations.

​
Target kinds

Each webhook has one target.
TargetUse it when
agentAn AI agent reasons over the event.
jobA background target runs.
workflowA 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" }
  ]
}
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

APIStart here
RESTWebhook definitions and webhook invocation.
MCPAutomation tools available to assistants.