Create and test a webhook

Create a webhook that passes support tickets to a project agent, then test it and inspect its webhook events. A webhook is a project URL that external services post to. Veryfront stores each delivery as a webhook event. When the target is an agent, task, or workflow, an event that passes the filter starts a run of that target. A webhook with the event target stores its events and starts no run. You need an existing agent and an API credential with project.agents.write in the project. Listing events needs project.agents.read. The REST run example also needs project.runs.write, and reading the run needs project.runs.read. The example uses triage-agent in support-assistant. Export the credential as VERYFRONT_API_KEY. The examples use curl, jq, and uuidgen.

1. Create the webhook

Create the webhook with POST /projects/{project_reference}/webhooks:

create-webhook.sh

curl -X POST https://api.veryfront.com/projects/support-assistant/webhooks \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage new tickets",
    "target": {"kind":"agent","id":"triage-agent","conversation_mode":"none"},
    "prompt_template": "Classify this support ticket and suggest the next action: {{payload.ticket.description}}",
    "event_filter": {
      "mode": "all",
      "conditions": [{"path":"type","operator":"equals","value":"ticket.created"}]
    }
  }'

target: What an event starts. kind is agent, task, or workflow. To only store events, use {"kind":"event","id":"event"}.
prompt_template: The prompt built from the payload. Required for every target except event. Omit it for an event target, which rejects it.
event_filter: Up to 50 conditions on payload paths, combined with mode all or any.

The new webhook is enabled. Only an enabled webhook accepts deliveries from senders. Save three values from the response:

webhook.id as WEBHOOK_ID. Pass it as webhook_id to the other webhook operations.
webhook.project_id as PROJECT_ID.
webhook.ingress_id as INGRESS_ID. Senders post to the URL that contains it.

The response returns webhook_secret only once. Save it as WEBHOOK_SECRET for the sender. The MCP create_webhook tool takes the same fields. The GraphQL createWebhook mutation takes them in camelCase: promptTemplate, eventFilter, and target.conversationMode.

2. Test the webhook

Run the webhook by hand with the GraphQL runWebhook mutation:

test-webhook.sh

curl --fail-with-body -X POST https://api.veryfront.com/graphql \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"query\": \"mutation RunWebhook(\$input: RunWebhookInput!) { runWebhook(input: \$input) { id status canonicalRunId errorMessage } }\",
    \"variables\": {
      \"input\": {
        \"projectReference\": \"support-assistant\",
        \"id\": \"$WEBHOOK_ID\",
        \"payload\": {\"type\":\"ticket.created\",\"ticket\":{\"id\":\"1001\",\"description\":\"I need help updating my subscription.\"}}
      }
    }
  }" > webhook-result.json

jq -e 'if .errors then error("Running the webhook failed") else .data.runWebhook end' webhook-result.json

The call applies the filter and target as a sender’s delivery does. It returns the webhook event it created. The MCP run_webhook tool takes webhook_id and payload and does the same. On REST, start a run with POST /runs and a webhook source. The payload goes in input:

run-webhook.sh

RUN_IDEMPOTENCY_KEY=$(uuidgen) || exit 1
export RUN_IDEMPOTENCY_KEY

curl --fail-with-body -X POST https://api.veryfront.com/runs \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RUN_IDEMPOTENCY_KEY" \
  -d "{
    \"project_id\": \"$PROJECT_ID\",
    \"source\": {\"type\":\"webhook\",\"id\":\"$WEBHOOK_ID\"},
    \"input\": {\"type\":\"ticket.created\",\"ticket\":{\"id\":\"1001\",\"description\":\"I need help updating my subscription.\"}}
  }"

POST /runs returns the run, not the webhook event. It fails when the event starts no run, for example when the filter stops the payload. Each runWebhook and run_webhook call creates a new webhook event. For POST /runs, send an Idempotency-Key header and reuse it with the same request when you retry. A repeated call with the same key and request returns the first run. If you omit the header when creating a root run, Veryfront generates a new key for each call, so a retry can start another run.

3. Send a delivery

Configure the external service to send a POST request to https://api.veryfront.com/webhooks/{ingress_id}:

send-delivery.sh

curl -X POST "https://api.veryfront.com/webhooks/$INGRESS_ID" \
  -H "X-Veryfront-Webhook-Secret: $WEBHOOK_SECRET" \
  -H "Idempotency-Key: ticket-1001-created" \
  -H "Content-Type: application/json" \
  -d '{"type":"ticket.created","ticket":{"id":"1001","description":"I need help updating my subscription."}}'

The sender authenticates with the X-Veryfront-Webhook-Secret header, not an API credential. The body is JSON of at most 64 KiB. A sender that cannot set custom headers, such as a GitHub repository webhook, passes the secret in the URL instead: https://api.veryfront.com/webhooks/{ingress_id}?secret={webhook_secret}. Use the header whenever the sender supports it. Send an Idempotency-Key header so a repeated delivery does not start a second run. For GitHub, Veryfront uses the X-GitHub-Delivery header as the key. A new delivery returns 202 with the webhook event. A repeated delivery returns 200 with the first event and duplicate: true. A delivery that reuses a key returns the first event, even when the payload differs. Use one key for each distinct delivery.

Verify the result

A POST /runs test returns the run itself, so inspect that run directly. For a GraphQL or MCP test call, or a sender delivery, check the status of the returned webhook event. When the event has a run ID (canonical_run_id in REST and MCP responses, canonicalRunId in GraphQL), read the run with GET /runs/{run_id}. A payload that the filter stops is stored with the status ignored and starts no run. List the events the webhook received with GET /projects/{project_reference}/webhooks/{webhook_id}/events. The GraphQL webhookEvents query and the MCP list_webhook_events tool return the same events:

list-webhook-events.sh

curl --fail-with-body "https://api.veryfront.com/projects/support-assistant/webhooks/$WEBHOOK_ID/events?limit=20" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY" > webhook-events.json

The response returns the newest events first in data. To read the next page, pass page_info.next as cursor. An event records what the sender delivered. The run records the work it started: progress, output, and errors.

Replay a webhook event

Replay an event to send its stored payload to the webhook’s current target again, for example after you fix a failing agent. Use POST /projects/{project_reference}/webhooks/{webhook_id}/events/{webhook_event_id}/replay. The GraphQL replayWebhookEvent mutation and the MCP replay_webhook_event tool do the same:

replay-webhook-event.sh

WEBHOOK_EVENT_ID=$(jq -er '.data[0].id' webhook-events.json) || exit 1

curl -X POST "https://api.veryfront.com/projects/support-assistant/webhooks/$WEBHOOK_ID/events/$WEBHOOK_EVENT_ID/replay" \
  -H "Authorization: Bearer $VERYFRONT_API_KEY"

The example replays the newest event in webhook-events.json. The replay creates a new webhook event and leaves the original unchanged.

Delivery errors

A delivery to the webhook URL can fail with these statuses:

Status	Cause
`400`	The secret is missing, the body is invalid, or the webhook is not enabled.
`404`	The `ingress_id` is unknown or the secret is wrong.
`409`	The idempotency key and the source event ID, such as `X-GitHub-Delivery`, match different webhook events.
`412`	Project automation is on hold.
`413`	The payload is larger than 64 KiB.

Conversation behavior

conversation_mode applies to agent targets only. It defaults to none.

create_new: Starts a new conversation. Use it for an agent that delegates with invoke_agent.
existing: Continues the conversation in conversation_id.
none: Runs the agent without a conversation.

create_new and existing also need project.conversations.write.

API references

Interface	Operations
REST	Create a webhook · List webhook events · Replay a webhook event · Create a run · Read a run
GraphQL	Create a webhook · Run a webhook · List webhook events · Replay a webhook event
MCP	Create a webhook · Run a webhook · List webhook events · Replay a webhook event

Get started

APIs

REST API

GraphQL API

MCP API

Create and test a webhook

1. Create the webhook

2. Test the webhook

3. Send a delivery

Verify the result

Replay a webhook event

Delivery errors

Conversation behavior

API references

​1. Create the webhook

​2. Test the webhook

​3. Send a delivery

​Verify the result

​Replay a webhook event

​Delivery errors

​Conversation behavior

​API references

1. Create the webhook

2. Test the webhook

3. Send a delivery

Verify the result

Replay a webhook event

Delivery errors

Conversation behavior

API references