Webhook Integration

Webhooks allow external services to notify VirtuousAI when events occur. This enables real-time integrations without polling.

Prerequisites

VirtuousAI account with CLI installed
Understanding of Automations
An external service that supports webhooks (Shopify, Stripe, etc.)

How Webhooks Work

External service sends HTTP POST to your webhook URL
VirtuousAI verifies the request signature
The associated automation is triggered
Actions execute with the webhook payload as input
VirtuousAI responds with success/failure

Creating a Webhook Endpoint

Create an automation with a webhook trigger:

vai automations create \
  --name "Shopify Order Webhook" \
  --trigger-type webhook \
  --config '{
    "path": "shopify/orders",
    "secret": "whsec_your_secret_here",
    "action": {
      "kind": "insight_delegate",
      "definition": {
        "prompt": "Process this new order: {{payload}}"
      }
    }
  }'

curl -X POST https://vai-dev.virtuousai.com/api/v1/automations \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shopify Order Webhook",
    "triggerType": "webhook",
    "config": {
      "path": "shopify/orders",
      "secret": "whsec_your_secret_here",
      "action": {
        "kind": "insight_delegate",
        "definition": {
          "prompt": "Process this new order: {{payload}}"
        }
      }
    }
  }'

This creates a webhook endpoint at:

https://vai-dev.virtuousai.com/webhooks/{org_id}/shopify/orders

Configuring External Services

Shopify

Go to Settings → Notifications → Webhooks
Click Create webhook
Select the event (e.g., Order creation)
Enter your VirtuousAI webhook URL
Set format to JSON

Stripe

stripe webhooks create \
  --url "https://vai-dev.virtuousai.com/webhooks/org_abc123/stripe/events" \
  --events checkout.session.completed,payment_intent.succeeded

GitHub

Go to Repository Settings → Webhooks
Click Add webhook
Enter your VirtuousAI webhook URL
Set content type to application/json
Enter your webhook secret
Select events to trigger

Webhook Security

Signature Verification

VirtuousAI verifies webhook signatures to ensure requests are authentic.

Configure the secret when creating the automation:

{
  "config": {
    "secret": "whsec_your_secret_here",
    "signatureHeader": "X-Shopify-Hmac-SHA256",
    "signatureAlgorithm": "sha256"
  }
}

IP Allowlisting

Restrict webhooks to specific IP addresses:

{
  "config": {
    "allowedIps": [
      "35.200.0.0/16",
      "13.225.0.0/16"
    ]
  }
}

Accessing Webhook Payload

The webhook payload is available in your action definition using template variables:

{
  "action": {
    "kind": "dlt_extract",
    "definition": {
      "source": "shopify",
      "resources": ["orders"],
      "filters": {
        "order_id": "{{payload.id}}"
      }
    }
  }
}

Available variables:

Variable	Description
`{{payload}}`	Full webhook body (JSON)
`{{payload.field}}`	Specific field from payload
`{{headers.X-Header}}`	Request header value
`{{query.param}}`	Query string parameter

Testing Webhooks

Local Testing

Use the CLI to simulate a webhook:

vai webhooks test auto_abc123 \
  --payload '{"id": "order_123", "total": 99.99}'

Debug Mode

Enable debug logging for webhook processing:

vai automations update auto_abc123 \
  --config '{"debug": true}'

View webhook logs:

vai events list \
  --resource-type automation \
  --resource-id auto_abc123 \
  --event-type webhook.*

Handling Failures

Retry Configuration

Configure automatic retries for failed webhook processing:

{
  "config": {
    "retries": {
      "enabled": true,
      "maxAttempts": 3,
      "backoffSeconds": [60, 300, 900]
    }
  }
}

Response Codes

Code	Meaning	VirtuousAI Behavior
`200`	Success	Mark as processed
`202`	Accepted	Mark as processing
`4xx`	Client error	No retry
`5xx`	Server error	Retry if configured
Timeout	No response	Retry if configured

Dead Letter Queue

Failed webhooks after all retries are sent to a dead letter queue:

vai webhooks dead-letter list --automation auto_abc123
# ID              RECEIVED           ERROR
# wh_abc123       2026-01-22 10:00   Action timeout
# wh_def456       2026-01-22 09:30   Rate limited

Replay a failed webhook:

vai webhooks replay wh_abc123

Rate Limiting

VirtuousAI applies rate limits to webhook endpoints:

Tier	Requests/minute	Burst
Free	60	10
Pro	300	50
Enterprise	Custom	Custom

If you exceed rate limits, webhooks return 429 Too Many Requests. Configure your source to handle retries.

Monitoring

Webhook Metrics

View webhook statistics:

vai webhooks stats auto_abc123 --period 24h
# Total received: 1,234
# Successful: 1,200 (97.2%)
# Failed: 34 (2.8%)
# Avg latency: 245ms

Alerting

Set up alerts for webhook issues:

{
  "config": {
    "alerts": {
      "failureThreshold": 10,
      "failureWindow": "5m",
      "notifyUrl": "https://hooks.slack.com/..."
    }
  }
}

Next Steps

Automations Reference

Deep dive into automation configuration

Events API

Query webhook events and logs

API Reference

Complete REST API documentation

Webhook Integration

Automations Reference

Events API

API Reference

On this page