Webhooks

Register a webhook URL to receive event notifications when assets are created, verified, or certificates are updated.

Request

POST /api/v1/webhooks

Headers

Body

Valid event types

If events is omitted, all valid events are subscribed.

Example

curl -X POST https://api.provenance.guru/api/v1/webhooks \
  -H "Authorization: Bearer pk_prov_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/provenance",
    "events": ["verification.completed", "certificate.issued"]
  }'

Response

Returns 201 Created:

{
  "id": "webhook-uuid",
  "url": "https://your-app.com/webhooks/provenance",
  "events": ["verification.completed", "certificate.issued"],
  "account_id": "your-account-uuid",
  "status": "active",
  "created_at": "2026-06-15T12:00:00.000Z",
  "message": "Webhook registered. Webhook delivery will be enabled in a future release."
}

Note: Webhook delivery is not yet active. Registration stores your URL and event preferences for when delivery is enabled in a future release.

Errors

Future delivery format

When delivery is enabled, payloads will be sent as POST requests to your registered URL with a JSON body containing the event type, timestamp, and relevant asset/certificate data. Signature verification will be documented at that time.