Skip to main content
Webhooks allow your application to receive push notifications when events occur on the CREDEBL platform. Register an HTTPS endpoint for your organization and CREDEBL will POST event payloads to that URL as events happen.

​
Authentication

All webhook endpoints require a JWT bearer token. Managing webhooks is restricted to organization Owner and Admin roles (read access is also available to Issuer and Verifier roles). 
Authorization: Bearer <your-jwt-token>

​
Base path

All webhook endpoints are rooted at /webhooks.

​
Register a webhook

POST /webhooks/orgs/:orgId/register Register a webhook URL for an organization. Required roles: owner, admin

​
Path parameters

​
orgId
string
required
UUID of the organization to register the webhook for.

​
Request body

​
webhookUrl
string
required
A valid URL that CREDEBL will POST event payloads to.
​
webhookSecret
string
Optional shared secret used for payload verification. Must be at least 16 characters long.

​
Example

curl -X POST http://localhost:5000/webhooks/orgs/6e672a9c-64f0-4d98-b312-f578f633800b/register \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.example.com/webhooks/credebl"
  }'

​
Response

​
statusCode
number
201 on success.
​
message
string
Confirmation message.
​
data
object
The registered webhook record.

​
Get webhook URL

GET /webhooks/orgs/webhookurl Retrieve the registered webhook URL for an organization or tenant. Required roles: owner, admin, issuer, verifier

​
Query parameters

​
orgId
string
Organization ID to look up the webhook for.
​
tenantId
string
UUID of a specific tenant to look up.

​
Example

curl "http://localhost:5000/webhooks/orgs/webhookurl?orgId=6e672a9c-64f0-4d98-b312-f578f633800b" \
  -H "Authorization: Bearer <token>"

​
Update a webhook

PATCH /webhooks/orgs/:orgId Update the webhook URL or secret for an organization. Required roles: owner, admin

​
Path parameters

​
orgId
string
required
UUID of the organization whose webhook to update.

​
Request body

​
webhookUrl
string
New webhook endpoint URL.
​
webhookSecret
string
New shared secret. Must be at least 16 characters long.

​
Example

curl -X PATCH http://localhost:5000/webhooks/orgs/6e672a9c-64f0-4d98-b312-f578f633800b \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.example.com/webhooks/credebl-v2"
  }'

​
Webhook payload structure

The platform POSTs event data to your registered URL using the WebhookResponseDto structure:
​
webhookUrl
string
The URL the payload was delivered to.
​
data
object
The event-specific payload from the underlying Aries agent or platform service.
The exact shape of data depends on the event type (connection, credential, or proof) and the DIDComm protocol used. Inspect the payloads your endpoint receives to understand the structure for your specific setup.

​
Error responses

StatusMeaning
400 Bad RequestInvalid orgId, missing webhookUrl, or webhookSecret shorter than 16 characters.
401 UnauthorizedJWT token missing or expired.
403 ForbiddenInsufficient role — only owner and admin can register or update webhooks.

Build docs developers (and LLMs) love

Get started for freeTalk to us