# Candidate Documents API — Webhooks

The Candidate Documents API emits the following webhook events. All events share the same `candidatedocuments` domain and deliver a full `CandidateDocumentsResponseDTO` 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 |
|  --- | --- |
| `CandidateDocumentsCreatedEvent` | Fired when a candidate documents feature is created for a candidate |
| `CandidateDocumentsDocumentCollectedEvent` | Fired when a candidate uploads a document in the feature |
| `CandidateDocumentsForwardedEvent` | Fired when the document collection is forwarded |
| `CandidateDocumentsStatusTransitionedEvent` | Fired when the feature status transitions to a new value |
| `CandidateDocumentsFinishedEvent` | Fired when the document collection feature is completed |
| `CandidateDocumentsClosedEvent` | Fired when the document collection feature is closed |


## Payload

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

```json
{
  "webhookId": "wh_abc123",
  "idempotencyId": "a3f2c1d4-5e6f-...",
  "domain": "candidatedocuments",
  "event": "CandidateDocumentsDocumentCollectedEvent",
  "version": 2,
  "timestamp": 1713384000000,
  "payload": {
    "id": "feat_abc123",
    "featureId": "ftr_xyz",
    "candidateId": "cand_abc",
    "vacancyId": "vac_abc",
    "companyId": "cmp_xyz",
    "isClosed": false,
    "status": {
      "code": "IN_PROGRESS",
      "descriptionCode": null,
      "date": "2024-04-17T20:00:00.000Z",
      "notificationDelay": null
    },
    "documents": [
      {
        "documentId": "doc_abc",
        "name": "CV",
        "content": "Please upload your CV",
        "isRequired": true,
        "link": "https://storage.example.com/cv.pdf",
        "answeredAt": "2024-04-17T20:05:00.000Z"
      }
    ]
    // .. full CandidateDocumentsDTO
  }
}
```

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

## 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.