---
title: "Receive a webhook"
method: POST
path: "reportEvent"
tags: ["Webhooks"]
---

# Receive a webhook

`POST reportEvent` (webhook)

Implement this POST handler on your own HTTPS server to receive signed change notifications from ProBB AI. This is your receiver, not a ProBB AI API URL.

## Before you call

Configure an endpoint in Settings → Developer and store its signing secret. Read raw bytes and verify webhook-id, webhook-timestamp, and webhook-signature before parsing JSON.

## What happens next

Durably record the event ID and processing intent, then respond promptly with any 2xx. Fetch the current resource with your API key when your background handler processes the event.

## Recovery

Events may arrive more than once or out of order. Deduplicate by verified event ID; verify a five-minute timestamp tolerance. Retryable delivery failures receive up to seven HTTP attempts. See the recovery guide for replay and catch-up.

[Follow the complete workflow](/integration-webhooks/) · [Errors and retries](/api-errors/)

## Headers

- `webhook-id` string, required
- `webhook-timestamp` string, required
- `webhook-signature` string, required

## Payload

- union
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'batch.completed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `batchId` string, required: Identifier returned when the batch was accepted; use it to retrieve item outcomes.
      - `succeeded` integer, required: Number of successful batch items; for interviews this means invitation admission, not candidate completion.
      - `failed` integer, required: Number of batch items that finished with a failure.
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'report.result_ready', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
      - `attemptId` string, nullable, required: Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available.
      - `resultRevision` string, required: Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication.
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'report.deleted', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'interview.invited' | 'interview.started' | 'interview.completed' | 'interview.expired' | 'interview.preparation_failed' | 'interview.result_ready' | 'interview.result_failed' | 'interview.invitation_failed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
      - `interviewId` string, required: Logical interview attempt ID returned by invitation. A reinterview receives a new ID.
      - `resultRevision` string, nullable, required: Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication.
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'report.completed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
      - `attemptId` string, required: Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available.
      - `status` 'completed', required: Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation.
      - `code` unknown, required
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'report.failed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
      - `attemptId` string, required: Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available.
      - `status` 'failed', required: Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation.
      - `code` 'ANALYSIS_FAILED', required: Stable machine-readable outcome or error code; null when no code applies.
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'report.requires_action', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
      - `attemptId` string, required: Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available.
      - `status` 'requires_action', required: Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation.
      - `code` 'CANDIDATE_JOB_MISMATCH', required: Stable machine-readable outcome or error code; null when no code applies.
  - object
    - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
    - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
    - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
    - `type` 'webhook.test', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
    - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
      - `message` 'ProBB webhook test', required: Human-readable summary. Use code/reason, not message text, for programmatic error handling.

## Acknowledgement `200`

Return any 2xx after durably recording the event; no response body is required.

---

[API](https://skmtc.dev/probbai/apis/probb-ai-customer-api.md) · [All operations](https://skmtc.dev/probbai/apis/probb-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/probbai/apis/probb-ai-customer-api/revisions/33a3294530e4?raw)