Webhooks API Reference
Complete API reference for managing webhooks in ConsentProof.
Create Webhook
POST /api/v1/webhooks
Request Body
{
"url": "https://your-app.com/webhooks/consentproof",
"events": ["consent.created", "consent.revoked"],
"description": "Production webhook",
"secret": "optional_custom_secret"
}Note: The secret field is optional. If not provided, a secure secret will be auto-generated for you (prefixed with whsec_).
Response
{
"success": true,
"data": {
"id": "wh_abc123",
"url": "https://your-app.com/webhooks/consentproof",
"events": ["consent.created", "consent.revoked"],
"secret": "whsec_a1b2c3d4e5f6...",
"isActive": true,
"createdAt": "2024-01-15T10:30:00Z"
},
"meta": {
"timestamp": "2024-01-15T10:30:00Z",
"message": "Save the webhook secret now - it will not be shown again."
}
}Important: The webhook secret is only returned in the response when the webhook is created. Make sure to save it securely as it will not be shown again. You'll need this secret to verify webhook signatures.
List Webhooks
GET /api/v1/webhooks
{
"success": true,
"data": [
{
"id": "wh_abc123",
"url": "https://your-app.com/webhooks/consentproof",
"events": ["consent.created", "consent.revoked"],
"isActive": true,
"lastTriggered": "2024-01-15T12:00:00Z",
"deliveryStats": {
"total": 150,
"successful": 148,
"failed": 2
}
}
]
}Get Webhook by ID
GET /api/v1/webhooks/:id
{
"success": true,
"data": {
"id": "wh_abc123",
"url": "https://your-app.com/webhooks/consentproof",
"events": ["consent.created", "consent.revoked"],
"description": "Production webhook",
"isActive": true,
"createdAt": "2024-01-15T10:30:00Z",
"lastTriggered": "2024-01-15T12:00:00Z"
}
}Update Webhook
PUT /api/v1/webhooks/:id
{
"isActive": false,
"events": ["consent.created"]
}Delete Webhook
DELETE /api/v1/webhooks/:id
{
"success": true,
"data": {
"message": "Webhook deleted successfully"
}
}Get Delivery History
GET /api/v1/webhooks/:id/deliveries
Retrieves the delivery history for a webhook, including successful and failed attempts.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number (default: 1) |
| limit | integer | Items per page (default: 20) |
{
"success": true,
"data": [
{
"id": "del_xyz789",
"webhookId": "wh_abc123",
"event": "consent.created",
"statusCode": 200,
"success": true,
"responseTime": 245,
"attemptedAt": "2024-01-15T12:00:00Z"
},
{
"id": "del_xyz790",
"webhookId": "wh_abc123",
"event": "consent.created",
"statusCode": 500,
"success": false,
"error": "Internal server error",
"responseTime": 5000,
"attemptedAt": "2024-01-15T11:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 150
}
}Test Webhook
POST /api/v1/webhooks/:id/test
Sends a test webhook payload to verify your endpoint is configured correctly.
{
"success": true,
"data": {
"delivered": true,
"statusCode": 200,
"responseTime": 156,
"message": "Test webhook delivered successfully"
}
}Available Events
consent.createdTriggered when a user gives consent to a policy.
consent.revokedTriggered when a user withdraws consent for a policy.
policy.createdTriggered when a new policy version is created.
policy.updatedTriggered when a policy is updated or deactivated.