---
title: Webhooks
path: reference/webhooks
status: published
---

# Webhooks Reference

Endpoint reference for webhook management. For the guide, see [Events and Webhooks](../core-concepts/events-and-webhooks). For signature verification, see [Webhook Signatures](../advanced/webhook-signatures).

**Base path:** `/v1/webhooks/`

## GET /v1/webhooks

List webhooks.

Response:

```json
{
  "webhooks": [
    {
      "id": "wh_abc",
      "name": "rotation-alerts",
      "url": "https://...",
      "events": ["secret.rotated", "secret.expiring"],
      "enabled": true,
      "status": "healthy",
      "created_at": "..."
    }
  ]
}
```

**Scope:** `admin`.

## POST /v1/webhooks

Create.

Body:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | |
| `url` | Yes | HTTPS endpoint |
| `secret` | Yes | Signing secret (>= 32 bytes recommended) |
| `events` | Yes | Array of event types |
| `filters.path_prefix` | No | Restrict to paths |
| `filters.secret_type` | No | |
| `filters.tags` | No | |
| `enabled` | No | Default true |

Response `201 Created`: webhook object.

**Scope:** `admin`.

## GET /v1/webhooks/{id}

Includes delivery statistics:

```json
{
  "id": "wh_abc",
  "statistics": {
    "deliveries_24h": 47,
    "success_rate_24h": 0.98,
    "avg_latency_ms": 180
  },
  "last_delivery": {
    "id": "del_xyz",
    "timestamp": "...",
    "status": "success",
    "response_code": 200
  }
}
```

## PATCH /v1/webhooks/{id}

Update.

## DELETE /v1/webhooks/{id}

## POST /v1/webhooks/{id}/test

Send a test event.

Response:

```json
{
  "delivery_id": "del_test",
  "status": "success",
  "response_code": 200,
  "duration_ms": 156
}
```

## GET /v1/webhooks/{id}/deliveries

List deliveries.

Query: `status` (`success`|`failed`|`pending`), `limit`, `cursor`.

Response:

```json
{
  "deliveries": [
    {
      "id": "del_xyz",
      "event_id": "evt_abc",
      "event_type": "secret.rotated",
      "timestamp": "...",
      "status": "success",
      "response_code": 200,
      "duration_ms": 245,
      "attempt": 1
    }
  ],
  "cursor": null,
  "has_more": false
}
```

## POST /v1/webhooks/{id}/deliveries/{delivery_id}/retry

Force retry of a failed delivery.

## Event types

| Type | Description |
|------|-------------|
| `secret.created` | |
| `secret.updated` | |
| `secret.deleted` | |
| `secret.rotated` | |
| `secret.expiring` | |
| `secret.expired` | |
| `secret.accessed` | Noisy; use with filters |
| `policy.created` / `.updated` / `.deleted` | |
| `policy.binding.created` / `.deleted` | |
| `policy.violation` | Access denied event |
| `rotation.due` | Includes `due_now` flag at actual rotation |
| `rotation.overdue` | |
| `rotation.completed` | |
| `rotation.failed` | |
| `certificate.issued` | |
| `certificate.renewed` | |
| `certificate.revoked` | |
| `certificate.expiring` | |
| `dynamic.lease.created` | |
| `dynamic.lease.renewed` | |
| `dynamic.lease.revoked` | |
| `dynamic.lease.expired` | |
| `federation.sync.completed` | |
| `federation.sync.failed` | |
| `federation.backend.unreachable` | |

## Delivery headers

```
X-ScaiVault-Event-Id: evt_abc
X-ScaiVault-Event-Type: secret.rotated
X-ScaiVault-Signature: sha256=...
X-ScaiVault-Timestamp: 1714478400
User-Agent: ScaiVault-Webhook/1.0
```

Verify signature before trusting the payload. See [Webhook Signatures](../advanced/webhook-signatures).

## Retry schedule

On non-2xx or timeout:

- Attempt 1: immediate
- Attempt 2: 30s
- Attempt 3: 5min
- Attempt 4: 30min
- Attempt 5: 2h
- Attempt 6: 8h
- Attempt 7: 24h
- After attempt 7: marked failed

Your endpoint must return 2xx within 10 seconds.

## Related

- [Events and Webhooks (Concepts)](../core-concepts/events-and-webhooks)
- [Webhook Signatures](../advanced/webhook-signatures)
- [Subscriptions](./subscriptions)