Webhook events

VantageClaw delivers events as JSON envelopes shaped consistently across every event type. v1 ships a single event so partners have something concrete to test against; the vocabulary grows as resource families ship.

Envelope shape

Every delivery body is a JSON object with this shape:

{
  "event": "vc.test.ping",
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subscription_id": "wh_11111111-2222-3333-4444-555555555555",
  "occurred_at": "2026-05-23T18:00:00.000000Z",
  "data": {
    "message": "integration test"
  }
}

Field	Type	Description
`event`	string	Dot-namespaced event type. Always `vc.<category>.<action>`.
`id`	string	Unique event ID prefixed `evt_`. Stable across retries — use for idempotency.
`subscription_id`	string	The `wh_<uuid>` your subscription was created with.
`occurred_at`	string	ISO 8601 UTC timestamp of when the event was generated, not when it was delivered.
`data`	object	Event-specific payload. Shape varies by `event` type — see below.

The body is serialized with stable key ordering and no whitespace — this is the exact byte stream signed by X-VC-Signature. Do not re-serialize before verifying.

Event types

`vc.test.ping`

Fired by POST /api/v1/partner/webhooks/{id}/test. The only event in v1. Used to exercise the full signature + delivery pipeline against your endpoint without waiting for a real platform event. data shape:

{
  "message": "integration test"
}

The test event flows through the same dispatch pipeline as production events — same retry schedule, same signature algorithm, same DNS re-resolution. A successful vc.test.ping end-to-end means your integration is ready to receive any future event type without changes to your verification code. See the integration test guide for the full readiness checklist.

Reserved event prefixes

Future events will follow the vc.<category>.<action> convention. The following category prefixes are reserved but not yet emitting:

vc.lead.* — lead lifecycle events
vc.intake.* — intake form submissions
vc.record.* — record-level CRUD events
vc.skill.* — skill execution events
vc.agent.* — agent invocation events

Subscriptions may include reserved event names in the events array at create time without error — they simply never fire until the corresponding category ships. This lets you build your handler ahead of the event going live.

In v1 the only event source is the explicit test endpoint (POST /api/v1/partner/webhooks/{id}/test), which fires regardless of whether vc.test.ping is listed in your subscription’s events array. Once real platform events ship, the events array becomes the filter that determines which categories your endpoint receives.

Getting started

Guides

Webhooks

Reference

Envelope shape

Event types

`vc.test.ping`

Reserved event prefixes

​Envelope shape

​Event types

​vc.test.ping

​Reserved event prefixes

Envelope shape

Event types

`vc.test.ping`

Reserved event prefixes