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

# 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](/webhooks/security) for the algorithm.
4. **Process** — Once verified, route the envelope to your application logic. Idempotent processing is strongly recommended — see [Delivery semantics](#delivery-semantics) below.

## Creating a subscription

```bash theme={null}
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`):

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

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

## 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

```bash theme={null}
# 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:

```bash theme={null}
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

<Columns cols={2}>
  <Card title="Webhook events" icon="list" href="/webhooks/events">
    The current event vocabulary and envelope shape.
  </Card>

  <Card title="Webhook security" icon="shield-check" href="/webhooks/security">
    HMAC verification algorithm, replay defense, sample implementations.
  </Card>
</Columns>