Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coverbase.com/llms.txt

Use this file to discover all available pages before exploring further.

The Webhooks API manages outbound webhook subscriptions. For payload format, signature verification, and delivery guarantees, see the Webhooks reference page.

​
Register a webhook

​
method
POST
POST /v1/webhooks
Registers a new webhook endpoint subscribed to a list of event types.

​
Request body

​
url
string
required
The HTTPS endpoint Coverbase will POST to. Must be a publicly reachable URL.
​
events
array
required
Array of event type strings to subscribe to in dot-notation format (e.g., vendor.created, assessment.completed). See the event taxonomy for available types. The external API uses dot-notation (vendor.created) which maps to internal enum values (VENDOR_CREATED).
​
secret
string
required
A shared secret used to sign deliveries with HMAC SHA256. Provide a high-entropy random string and store it in your secrets manager.
​
description
string
Optional human-readable label for the webhook. Visible in the dashboard.
​
enabled
boolean
Defaults to true. Set to false to register the webhook without activating it.

​
Example request

curl -X POST "https://api.coverbase.app/v1/webhooks" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/coverbase",
    "events": [
      "vendor.created",
      "assessment.completed",
      "evaluation.flagged",
      "contract.renewal_due",
      "workflow.checkpoint"
    ],
    "secret": "whsec_a1b2c3d4e5f6...",
    "description": "Primary GRC integration"
  }'

​
Example response

{
  "id": "cbwh_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
  "url": "https://hooks.example.com/coverbase",
  "events": [
    "vendor.created",
    "assessment.completed",
    "evaluation.flagged",
    "contract.renewal_due",
    "workflow.checkpoint"
  ],
  "description": "Primary GRC integration",
  "enabled": true,
  "created_at": 1746576000
}
The secret is never returned in any response after creation. Save it on your side at registration time. If lost, rotate via the update endpoint.

​
List webhooks

​
method
GET
GET /v1/webhooks
Returns all webhook subscriptions for the org.

​
Example response

{
  "data": [
    {
      "id": "cbwh_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
      "url": "https://hooks.example.com/coverbase",
      "events": ["vendor.created", "assessment.completed"],
      "description": "Primary GRC integration",
      "enabled": true,
      "created_at": 1746576000
    }
  ]
}

​
Update a webhook

​
method
PATCH
PATCH /v1/webhooks/{webhook_id}
Updates one or more fields on an existing webhook. Use this to add or remove event subscriptions, rotate the secret, or disable a webhook without deleting it.

​
Example request

cURL
curl -X PATCH "https://api.coverbase.app/v1/webhooks/cbwh_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "vendor.created",
      "vendor.status_changed",
      "assessment.completed",
      "evaluation.flagged"
    ]
  }'
Rotate the signing secret:
cURL
curl -X PATCH "https://api.coverbase.app/v1/webhooks/cbwh_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "secret": "whsec_newsecretvalue..." }'

​
Delete a webhook

​
method
DELETE
DELETE /v1/webhooks/{webhook_id}
Permanently removes the webhook subscription. In-flight deliveries are not cancelled; new events stop firing.
cURL
curl -X DELETE "https://api.coverbase.app/v1/webhooks/cbwh_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9" \
  -H "Authorization: Bearer <api-key>"
Returns 204 No Content on success.

​
Test a webhook

​
method
POST
POST /v1/webhooks/{webhook_id}/test
Sends a test event to the webhook URL. Useful for confirming endpoint reachability and signature verification during integration setup.

​
Request body

​
event_type
string
Optional event type to simulate. Defaults to webhook.test. Must be one of the events the webhook is subscribed to (or webhook.test).

​
Example request

cURL
curl -X POST "https://api.coverbase.app/v1/webhooks/cbwh_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9/test" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "assessment.completed" }'

​
Example response

{
  "event_id": "cbevt_test_8b3c1a4d9e7f2c5b6a8d1e3f9c7b4a2e",
  "delivered": true,
  "response_status": 200,
  "response_time_ms": 142,
  "attempted_at": 1746576180
}

​
Error responses

StatusCodeWhen
400invalid_urlThe URL is malformed, not HTTPS, or not publicly reachable.
400invalid_event_typeOne or more event types are not recognized.
400weak_secretThe provided secret does not meet minimum entropy requirements.
404webhook_not_foundThe provided webhook_id does not exist or is not accessible to the API key.