Webhooks overview

Subscribe to platform events, receive HMAC-signed deliveries, and verify them safely.

Webhooks let your application react to events happening inside VantageClaw without polling. The platform pushes an HMAC-signed HTTPS POST to a URL you control whenever a subscribed event fires.

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"]
  }'

Successful response (201):

{
  "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_..."
}

The secret field is returned only on creation. Subsequent reads (GET /api/v1/partner/webhooks) omit it. If you lose the secret, delete the subscription and create a new one to receive a fresh secret.

URL requirements

Subscription URLs are validated server-side at create time to prevent SSRF attacks against internal infrastructure:

• 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.

The dispatcher re-resolves DNS at delivery time, so DNS-rebinding attacks (resolving to a public IP at create time then flipping to internal) are also rejected. If your URL legitimately moves to a different host, the new host must also pass the same validation.

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

The failures audit endpoint returns recent delivery failures for a subscription, cursor-paginated newest-first:

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"

Pass the next_cursor value from the response as ?cursor=... to fetch the next page. next_cursor: null means no more pages.

Next steps

Webhook events

The current event vocabulary and envelope shape.

Webhook security

HMAC verification algorithm, replay defense, sample implementations.