Assess API · v1
Webhooks
Receive real-time push notifications for candidate lifecycle events. Configure webhook endpoints in your dashboard under Developer → Webhooks or via the API. All payloads are signed with HMAC-SHA256.
GET
https://praxicraft.com/api/v1/public/webhooks/webhooks:readAuth: Bearer ct_live_…
List Webhooks
Returns all configured webhook endpoints for your organisation.
Query / Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| cursor | string | optional | Opaque pagination cursor — pass the value from `next` to fetch the next page |
| page_size | integer | optional | Results per page, max 100 (default: 20) |
Response Fields
| Field | Type | Description |
|---|---|---|
| id | uuid | Webhook UUID |
| url | string | Target endpoint URL |
| is_active | boolean | Whether the webhook is enabled |
| is_verified | boolean | Whether a test ping has been confirmed |
| events | array | List of subscribed event types |
| created_at | ISO 8601 | When the webhook was registered |
| last_triggered_at | ISO 8601|null | Timestamp of the last successful delivery |
Example Response
JSON
{
"next": null,
"previous": null,
"results": [
{
"id": "550e8400-...",
"url": "https://api.acme.com/webhooks",
"is_active": true,
"is_verified": true,
"events": ["assessment.completed", "candidate.passed"],
"created_at": "2025-02-10T12:00:00Z",
"last_triggered_at": "2025-03-20T16:45:00Z"
}
]
}POST
https://praxicraft.com/api/v1/public/webhooks/webhooks:writeAuth: Bearer ct_live_…
Create Webhook
Register a new endpoint to receive event notifications.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | required | Your HTTPS endpoint URL |
| event_types | array | required | List of events to subscribe to |
| description | string | optional | Internal label |
Response Fields
| Field | Type | Description |
|---|---|---|
| id | uuid | New webhook ID |
| signing_secret | string | Use this to verify X-Praxicraft-Signature headers |
Example Response
JSON
{
"id": "550e8400-...",
"signing_secret": "whsec_..."
}POST
https://praxicraft.com/api/v1/public/webhooks/:id/test/webhooks:writeAuth: Bearer ct_live_…
Test Webhook Endpoint
Sends a test ping to the specified webhook endpoint to verify your implementation. Updates `is_verified` to true upon success.
Query / Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | uuid | required | The webhook endpoint UUID |
Response Fields
| Field | Type | Description |
|---|---|---|
| message | string | Test outcome message |
| status_code | integer | HTTP status returned by your server |
| is_verified | boolean | Whether the endpoint is now verified |
Example Response
JSON
{
"message": "Test succeeded — endpoint responded with 200.",
"status_code": 200,
"is_verified": true
}POST
(your endpoint URL)Auth: HMAC-SHA256 (X-Praxicraft-Signature)
Signature Verification
Every webhook request includes an `X-Praxicraft-Signature` header. Verify it using the signing secret shown in your webhook settings. Reject requests where the signature does not match.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
| X-Praxicraft-Signature | string | required | HMAC-SHA256 hex digest of the raw request body, keyed with your webhook signing secret |
| Content-Type | string | required | application/json |
Response Fields
| Field | Type | Description |
|---|---|---|
| event | string | Event type — see list below |
| created_at | ISO 8601 | Event timestamp (UTC) |
| data | object | Event-specific payload |
Example Response
JSON
// Python verification example
import hmac, hashlib
def verify(secret: str, raw_body: bytes, header_sig: str) -> bool:
expected = hmac.new(
secret.encode(), raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, header_sig)POST
(your endpoint URL)Auth: HMAC-SHA256
Event Types & Payloads
Subscribe to specific events when configuring a webhook endpoint. Unsubscribed events are never delivered to that endpoint.
Response Fields
| Field | Type | Description |
|---|---|---|
| assessment.started | event | Candidate started the assessment (session created) |
| assessment.completed | event | Candidate submitted all tasks and completed the assessment |
| candidate.passed | event | Session scored above the passing threshold |
| candidate.failed | event | Session scored below the passing threshold |
| candidate.violation | event | Proctoring violation detected (fullscreen exit or copy/paste) |
| invitation.expired | event | Invitation link passed its expiry date without being started |
| webhook.test | event | Test ping dispatched from the dashboard |
Example Response
JSON
// candidate.passed payload
{
"event": "candidate.passed",
"created_at": "2025-03-15T15:21:00Z",
"data": {
"session_id": "e1f2a3b4-...",
"assessment_id": "d290f1ee-...",
"assessment_slug": "senior-backend-screen",
"candidate_email": "jane@example.com",
"candidate_name": "Jane Doe",
"score": 255,
"max_score": 300,
"passed": true
}
}