Webhooks

Endpoint reference for webhook management. For the guide, see Events and Webhooks. For signature verification, see 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#

scdoc

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.

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.

Webhooks

GET /v1/webhooks#

POST /v1/webhooks#

GET /v1/webhooks/{id}#

PATCH /v1/webhooks/{id}#

DELETE /v1/webhooks/{id}#

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

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

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

Event types#

Delivery headers#

Retry schedule#

Related#