> ## Documentation Index
> Fetch the complete documentation index at: https://developers.vantageclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook events

> The current event vocabulary and envelope shape.

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:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](/guides/integration-test) 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.

<Note>
  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.
</Note>