Webhooks overview

​

Lifecycle

1. Subscribe — POST /api/v1/partner/webhooks with the URL you want events delivered to and the list of event types you care about. The response returns the subscription’s HMAC secret once — store it securely; it is not recoverable.
2. Receive — When a subscribed event fires, VantageClaw POSTs the signed envelope to your URL. Your endpoint must respond 2xx within 10 seconds to acknowledge receipt.
3. Verify — Every request carries X-VC-Signature and X-VC-Timestamp headers. Verify both before trusting the body. See Webhook security for the algorithm.
4. Process — Once verified, route the envelope to your application logic. Idempotent processing is strongly recommended — see Delivery semantics below.

​

Creating a subscription

curl https://app.vantageclaw.ai/api/v1/partner/webhooks \
  -H "Authorization: Bearer vck_test_REPLACE_ME.your_secret_half_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/vantageclaw",
    "events": ["vc.test.ping"]
  }'

{
  "id": "wh_a1b2c3d4-...",
  "organization_id": "org_...",
  "url": "https://example.com/webhooks/vantageclaw",
  "events": ["vc.test.ping"],
  "active": true,
  "auto_disabled_at": null,
  "consecutive_failures": 0,
  "created_at": "2026-05-23T18:00:00Z",
  "secret": "whsec_..."
}

​

URL requirements

• Must be https:// (no plaintext http://).
• Must resolve to a public IP address — RFC1918 ranges, loopback, and link-local addresses are rejected with 422.
• Must not be a .local mDNS name or any other non-public hostname.

​

Listing and deleting

# List all subscriptions for your org (secret omitted)
curl https://app.vantageclaw.ai/api/v1/partner/webhooks \
  -H "Authorization: Bearer vck_test_REPLACE_ME.your_secret_half_here"

# Delete a subscription
curl -X DELETE \
  https://app.vantageclaw.ai/api/v1/partner/webhooks/wh_a1b2c3d4-... \
  -H "Authorization: Bearer vck_test_REPLACE_ME.your_secret_half_here"

​

Delivery semantics

• At-least-once. A successful delivery may be re-sent if the network truncates between your 2xx and our acknowledgment. Design your handler to be idempotent — dedupe on the envelope’s id field (format evt_<uuid>).
• Retry schedule. Failed deliveries (non-2xx response, timeout, network error) retry on a fixed schedule: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 24 hours. After 7 total attempts the delivery is dead-lettered and recorded in the failures audit.
• HTTP timeout. Each attempt has a 10-second timeout. If your handler regularly takes longer than 10 seconds, acknowledge with 2xx first and process asynchronously.
• Auto-disable. After 20 consecutive failures, the subscription is auto-disabled (active: false, auto_disabled_at set). It stops receiving deliveries until you delete and recreate it.

​

Inspecting failures

curl 'https://app.vantageclaw.ai/api/v1/partner/webhooks/wh_a1b2c3d4-.../failures?limit=50' \
  -H "Authorization: Bearer vck_test_REPLACE_ME.your_secret_half_here"

​

Next steps