# Candidate Psychometric API — Webhooks

The Candidate Psychometric API emits the following webhook events. All events share the same `candidatepsychometricv2` domain and deliver a full `CandidatePsychometricResponseDTO` snapshot using the **V2** payload schema (camelCase fields).

See the [Webhooks guide](/docs/webhooks) for general information on payload structure, idempotency, and how to subscribe.

## Available Events

| Event | Description |
|  --- | --- |
| `CandidatePsychometricCreatedEvent` | Fired when a new candidate psychometric feature is created for a candidate |
| `CandidatePsychometricForwardedEvent` | Fired when the candidate psychometric feature is forwarded |
| `CandidatePsychometricStatusTransitionedEvent` | Fired when the psychometric feature status transitions to a new value |
| `CandidatePsychometricClosedEvent` | Fired when the candidate psychometric feature is closed |
| `CandidatePsychometricApprovedEvent` | Fired when the candidate psychometric test is approved |
| `CandidatePsychometricFinishedEvent` | Fired when the candidate completes the psychometric test and provider results are received |
| `CandidatePsychometricContactedAlternativelyEvent` | Fired when the candidate is reached through an alternative contact method |


## Payload

All events use **payload schema V2** (camelCase envelope) with a `CandidatePsychometricResponseDTO` in the `payload` field.

```json
{
  "webhookId": "wh_abc123",
  "idempotencyId": "a3f2c1d4-5e6f-...",
  "domain": "candidatepsychometricv2",
  "event": "CandidatePsychometricFinishedEvent",
  "version": 2,
  "timestamp": 1713384000000,
  "payload": {
    "id": "feat_abc123",
    "featureId": "ftr_xyz",
    "relationId": "rel_abc",
    "candidateId": "cand_abc",
    "vacancyId": "vac_abc",
    "companyId": "cmp_xyz",
    "isClosed": false,
    "status": {
      "code": "Approved",
      "descriptionCode": null,
      "date": "2024-04-17T20:00:00.000Z",
      "notificationDelay": null
    },
    "statusHistory": [
      {
        "code": "InTest",
        "descriptionCode": null,
        "date": "2024-04-17T19:00:00.000Z",
        "notificationDelay": null
      }
    ],
    "submissionId": "sub_abc123",
    "link": "https://psychometrics.hunty.com/t/abc123",
    "evaluationId": 4521,
    "evaluationName": "General Aptitude Battery",
    "reports": [
      {
        "name": "candidate",
        "url": "https://k8s-exp-api-stg.hunty.cloud/v2/candidates/psychometrics/company/cmp_xyz/psychometric/feat_abc123/report/candidate"
      }
    ],
    "createdAt": "2024-04-17T19:00:00.000Z",
    "updatedAt": "2024-04-17T20:00:00.000Z"
  }
}
```

For the schema definition, see the **Get Feature by ID** operation in the [API reference](/apis/candidate-psychometric-v2) — the `200` response shows the full interactive `CandidatePsychometricResponseDTO`.

## Subscribing

To subscribe to any of these events, follow the [subscription request process](/docs/webhooks#requesting-a-webhook-subscription) and specify the event name and your endpoint URL.