Skip to main content
All operations require authentication using Bearer tokens. Make sure you have your API credentials ready.
Webhook endpoints must be publicly accessible and return appropriate HTTP status codes.

​
Create Webhook

Create a new webhook endpoint to receive real-time notifications for various events. 
curl -X POST "https://secure-api.getclaro.ai/api/v2/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{
    "name": "Dataset Processing Notifications",
    "url": "https://your-app.com/webhooks/claro",
    "events": ["dataset.task.completed", "dataset.task.failed", "datasource.processed"],
    "headers": {
      "Authorization": "Bearer your-webhook-secret",
      "X-Custom-Header": "your-value"
    },
    "secret": "your-webhook-signing-secret"
  }'

​
List All Webhooks

Retrieve a paginated list of all your webhooks with their current status and statistics. 
curl -X GET "https://secure-api.getclaro.ai/api/v2/webhooks?page=1&limit=20&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get Webhook Details

Retrieve detailed information about a specific webhook including delivery logs and configuration. 
curl -X GET "https://secure-api.getclaro.ai/api/v2/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Update Webhook

Update webhook configuration including URL, events, headers. 
curl -X PATCH "https://secure-api.getclaro.ai/api/v2/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-update-id-456" \
  -d '{
    "name": "Updated Dataset Notifications",
    "events": ["dataset.task.completed", "dataset.task.failed", "dataset.task.started"],
    "headers": {
      "Authorization": "Bearer updated-webhook-secret",
      "X-API-Version": "v2"
    }
  }'

​
Test Webhook

Send a test payload to your webhook endpoint to verify connectivity and authentication. 
curl -X POST "https://secure-api.getclaro.ai/api/v2/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "webhook.test",
    "testPayload": {
      "message": "This is a test webhook delivery",
      "timestamp": "2024-03-14T17:30:00Z"
    }
  }'

​
Get Webhook Delivery Logs

Retrieve detailed delivery logs for a specific webhook. 
curl -X GET "https://secure-api.getclaro.ai/api/v2/webhooks/$WEBHOOK_ID/deliveries?page=1&limit=50&status=failed" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Retry Failed Delivery

Manually retry a failed webhook delivery. 
curl -X POST "https://secure-api.getclaro.ai/api/v2/webhooks/$WEBHOOK_ID/deliveries/$DELIVERY_ID/retry" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Delete Webhook

Permanently delete a webhook. This action cannot be undone. 
curl -X DELETE "https://secure-api.getclaro.ai/api/v2/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Webhook Requirements & Validation

​
URL Requirements

  • Must use HTTPS protocol
  • Must be publicly accessible
  • Must respond within 30 seconds
  • Must return HTTP status codes 200-299 for success

​
Authentication Headers

  • Custom headers are supported for authentication
  • Headers containing sensitive data are redacted in responses
  • Maximum 10 custom headers per webhook

​
Secret Validation

  • Minimum 16 characters required
  • Used for HMAC-SHA256 signature generation
  • Signature sent in X-Webhook-Signature header

​
Idempotency

  • Use Idempotency-Key header to prevent duplicate operations
  • Keys expire after 24 hours
  • Duplicate requests return the original response

​
Available Events

EventDescriptionPayload Includes
dataset.createdNew dataset createddatasetId, name, type
dataset.task.startedDataset task execution startedtaskId, type, datasetId
dataset.task.completedDataset task execution completedtaskId, results, duration
dataset.task.failedDataset task execution failedtaskId, error, details
dataset.updatedDataset metadata or structure updateddatasetId, changes
datasource.uploadedNew datasource uploadeddatasourceId, fileName
datasource.processedDatasource processing completeddatasourceId, status
webhook.testTest event for webhook validationtestPayload

​
Query Parameters

​
List Webhooks

  • page (integer): Page number (default: 1)
  • limit (integer): Items per page (default: 20, max: 100)
  • status (string): Filter by status (active, paused, failed)
  • event (string): Filter by event type

​
Get Delivery Logs

  • page (integer): Page number (default: 1)
  • limit (integer): Items per page (default: 50, max: 500)
  • status (string): Filter by delivery status (success, failed, pending)
  • event (string): Filter by event type
  • from (string): Start date (ISO 8601)
  • to (string): End date (ISO 8601)

​
Error Codes

CodeDescription
UNAUTHORIZEDAuthentication required
WEBHOOK_NOT_FOUNDWebhook doesn’t exist
DELIVERY_NOT_FOUNDDelivery record doesn’t exist
INVALID_URLWebhook URL is invalid or not HTTPS
INVALID_EVENTSOne or more events are not supported
SECRET_TOO_SHORTWebhook secret must be at least 16 chars
TOO_MANY_HEADERSMaximum 10 custom headers allowed
DUPLICATE_IDEMPOTENCY_KEYIdempotency key already used
WEBHOOK_LIMIT_EXCEEDEDMaximum webhook limit reached
DELIVERY_ALREADY_RETRIEDDelivery has already been retried

​
Webhook Payload Example

{
  "event": "dataset.task.completed",
  "timestamp": "2024-03-14T16:45:00Z",
  "webhookId": "webhook_550e8400-e29b-41d4-a716-446655440000",
  "deliveryId": "delivery_123",
  "data": {
    "taskId": "task_123",
    "datasetId": "dataset_123",
    "name": "Product Analysis Dataset",
    "type": "extraction",
    "status": "completed",
    "rowCount": 1500,
    "columnCount": 8,
    "processingTime": 45000,
    "completedAt": "2024-03-14T16:45:00Z",
    "stats": {
      "successfulRows": 1485,
      "failedRows": 15,
      "averageConfidence": 0.94
    }
  }
}