Start an agent, task or workflow when an external system sends a matching JSON event.
Steps
- Create a webhook for the project.
- Choose an agent, task or workflow target.
- 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
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
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.
Prompt template
For agent, task and workflow targets, the prompt template describes 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" }
]
}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.