> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger work from a webhook

> Turn external events into durable Veryfront runs.

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`

```bash title="Terminal" theme={null}
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](/cloud/rest/api-reference/webhooks/create-project-webhook), [Run Project Webhook](/cloud/rest/api-reference/webhooks/run-project-webhook) |
| MCP     | [Create Project Webhook](/cloud/mcp/tools/create-project-webhook), [Run Project Webhook](/cloud/mcp/tools/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.

```text theme={null}
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 theme={null}
{
  "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](/cloud/rest) | Webhook definitions and webhook invocation. |
| [MCP](/cloud/mcp)   | Automation tools available to assistants.   |