Skip to Content
API EndpointsWebhooks

Webhooks

Subscribe to real-time event notifications from Celper AI. Webhooks deliver HTTP POST requests to your endpoint when key events occur, such as interview analysis completion or candidate status changes.

Each company can register up to 5 webhooks. All webhook URLs must use HTTPS and cannot point to private or reserved IP ranges.

GET/v1/webhooks

Returns all webhooks registered for your company.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

curl https://api.celper.ai/v1/webhooks -H "X-API-Key: celp_your_api_key_here"
200Success
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://hooks.example.com/celper",
      "events": [
        "analysis_ready",
        "candidate_status_changed"
      ],
      "statusFilters": [
        "interviewed",
        "selected",
        "rejected"
      ],
      "isActive": true,
      "failureCount": 0,
      "lastDeliveryAt": "2026-04-10T16:00:00.000Z",
      "lastDeliveryStatus": "delivered",
      "createdAt": "2026-03-20T10:00:00.000Z",
      "updatedAt": "2026-04-10T16:00:00.000Z"
    }
  ]
}
403Insufficient role
POST/v1/webhooks

Register a new webhook endpoint. You must specify at least one event to subscribe to. The response includes a secret for verifying webhook signatures — store it securely, as it will not be returned again.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

Valid events:

  • analysis_ready — fired when interview analysis is complete
  • candidate_status_changed — fired when a candidate’s status changes
  • cv_analysis_complete — fired when CV analysis finishes
  • bulk_import_complete — fired when a bulk import job finishes

Valid status filters: new, invited, interviewed, selected, rejected, expired, failed, unevaluable

URL restrictions: Must be HTTPS. The following are blocked: localhost, private IPs (10.*, 172.16-31.*, 192.168.*), and metadata endpoints (169.254.*).

Body Parameters
ParameterTypeRequiredDescription
urlstringRequiredThe HTTPS endpoint URL to receive webhook events. Max 2048 characters. No private IPs.
eventsarrayRequiredArray of event types to subscribe to. Min 1 item.
statusFiltersarrayOptionalOptional array of candidate statuses to filter `candidate_status_changed` events.
curl -X POST https://api.celper.ai/v1/webhooks -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -d '{
  "url": "https://hooks.example.com/celper",
  "events": ["analysis_ready", "candidate_status_changed"],
  "statusFilters": ["interviewed", "selected", "rejected"]
}'
201Created
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "webhookId": "wh_abc123",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0..."
  }
}
409Limit exceeded
400Invalid URL
400Invalid event type
GET/v1/webhooks/{webhookId}

Returns details for a specific webhook. The signing secret is not included in the response.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

Path Parameters
ParameterTypeRequiredDescription
webhookIdstringRequiredThe unique identifier of the webhook.
curl https://api.celper.ai/v1/webhooks/wh_abc123 -H "X-API-Key: celp_your_api_key_here"
200Success
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "wh_abc123",
    "url": "https://hooks.example.com/celper",
    "events": [
      "analysis_ready",
      "candidate_status_changed"
    ],
    "statusFilters": [
      "interviewed",
      "selected",
      "rejected"
    ],
    "isActive": true,
    "failureCount": 0,
    "lastDeliveryAt": "2026-04-10T16:00:00.000Z",
    "lastDeliveryStatus": "delivered",
    "createdAt": "2026-03-20T10:00:00.000Z",
    "updatedAt": "2026-04-10T16:00:00.000Z"
  }
}
404Not found
PATCH/v1/webhooks/{webhookId}

Update an existing webhook’s URL, subscribed events, status filters, or active state. Only include the fields you want to change.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

Path Parameters
ParameterTypeRequiredDescription
webhookIdstringRequiredThe unique identifier of the webhook.
Body Parameters
ParameterTypeRequiredDescription
urlstringOptionalUpdated HTTPS endpoint URL. Max 2048 characters.
eventsarrayOptionalUpdated array of event types to subscribe to.
statusFiltersarrayOptionalUpdated array of status filters. Pass an empty array to clear filters.
isActivebooleanOptionalSet to `false` to pause delivery, `true` to resume.
curl -X PATCH https://api.celper.ai/v1/webhooks/wh_abc123 -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -d '{
  "events": ["analysis_ready", "candidate_status_changed", "cv_analysis_complete"],
  "isActive": true
}'
200Success
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "wh_abc123",
    "url": "https://hooks.example.com/celper",
    "events": [
      "analysis_ready",
      "candidate_status_changed",
      "cv_analysis_complete"
    ],
    "statusFilters": [
      "interviewed",
      "selected",
      "rejected"
    ],
    "isActive": true,
    "failureCount": 0,
    "lastDeliveryAt": "2026-04-10T16:00:00.000Z",
    "lastDeliveryStatus": "delivered",
    "createdAt": "2026-03-20T10:00:00.000Z",
    "updatedAt": "2026-04-11T08:30:00.000Z"
  }
}
400Validation error
DELETE/v1/webhooks/{webhookId}

Permanently delete a webhook. All pending deliveries will be cancelled.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

Path Parameters
ParameterTypeRequiredDescription
webhookIdstringRequiredThe unique identifier of the webhook.
curl -X DELETE https://api.celper.ai/v1/webhooks/wh_abc123 -H "X-API-Key: celp_your_api_key_here"
200Success
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "deleted": true
  }
}
404Not found
POST/v1/webhooks/{webhookId}/test

Send a test ping event to the webhook URL to verify connectivity. The test payload uses the same signature mechanism as real events.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

Path Parameters
ParameterTypeRequiredDescription
webhookIdstringRequiredThe unique identifier of the webhook.
curl -X POST https://api.celper.ai/v1/webhooks/wh_abc123/test -H "X-API-Key: celp_your_api_key_here"
200Success
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "tested": true
  }
}
404Not found

The test delivery uses the event type ping with the following payload:

{
  "test": true,
  "timestamp": "2026-04-11T12:00:00.000Z",
  "webhookId": "wh_abc123",
  "api_version": "v1"
}
POST/v1/webhooks/{webhookId}/rotate-secret

Generate a new signing secret for a webhook. The previous secret is immediately invalidated. Store the new secret securely — it will not be returned again.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

Path Parameters
ParameterTypeRequiredDescription
webhookIdstringRequiredThe unique identifier of the webhook.
curl -X POST https://api.celper.ai/v1/webhooks/wh_abc123/rotate-secret -H "X-API-Key: celp_your_api_key_here"
200Success
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "webhookId": "wh_abc123",
    "secret": "whsec_x9y8z7w6v5u4t3s2r1q0..."
  }
}
404Not found
GET/v1/webhooks/{webhookId}/deliveries

Returns a paginated list of delivery attempts for a specific webhook. Use this to debug delivery failures and monitor webhook health.

Scope: manage:webhooks | Role: owner or admin | Rate limit: webhooks (20 requests / 60s)

Path Parameters
ParameterTypeRequiredDescription
webhookIdstringRequiredThe unique identifier of the webhook.
Query Parameters
ParameterTypeRequiredDescription
limitnumberOptionalNumber of results to return. Min 1, max 50. Default: 20.
cursorstringOptionalPagination cursor from a previous response.
statusstringOptionalFilter by delivery status. Valid values: `"delivered"`, `"failed"`, `"exhausted"`.
curl "https://api.celper.ai/v1/webhooks/wh_abc123/deliveries?limit=10&status=failed" -H "X-API-Key: celp_your_api_key_here"
200Success
{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": [
    {
      "id": "del_abc123",
      "webhookId": "wh_abc123",
      "event": "analysis_ready",
      "status": "delivered",
      "attemptCount": 1,
      "httpStatus": 200,
      "createdAt": "2026-04-10T16:00:00.000Z",
      "lastAttemptAt": "2026-04-10T16:00:01.000Z"
    },
    {
      "id": "del_def456",
      "webhookId": "wh_abc123",
      "event": "candidate_status_changed",
      "status": "failed",
      "attemptCount": 3,
      "httpStatus": 500,
      "createdAt": "2026-04-10T15:30:00.000Z",
      "lastAttemptAt": "2026-04-10T15:45:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTEwIn0",
    "hasMore": true
  }
}
404Not found
Candidate ActionsRate Limiting