Webhook event catalog
Every supported event, why it is sent, what its payload means, and what your receiver should do.
Events announce a change; they do not contain the full report. Verify the signature before parsing, durably deduplicate the event ID, then fetch current state when needed. Notifications can be delayed or out of order. All examples below are synthetic.
Envelope and identities
Every envelope contains an event UUID, type, public schema version, UTC occurrence time, and event-specific data. The signed webhook-id header must match the envelope id. A retry or manual replay preserves the event ID but refreshes the signature timestamp.
Report attempt IDs identify analysis runs. Interview IDs identify logical interview attempts. A result revision identifies a publication. Save these separately; a completed interview and a ready evaluation are different events. Candidate emails, external references, documents, transcripts, and private links are not included.
Choose subscriptions
| Workflow | Events to consider |
|---|---|
| Resume analysis | report.completed, report.requires_action, report.failed |
| Detailed evidence synchronization | report.result_ready, interview.result_ready |
| Candidate interview progress | interview.invited, interview.started, interview.completed, interview.expired |
| Interview recovery | interview.preparation_failed, interview.result_failed, interview.invitation_failed |
| Bulk work | batch.completed |
| Downstream deletion | report.deleted |
| Receiver setup | webhook.test (sent by the test action) |
report.completed
An analysis published a completed report.
Receiver action: Read current report status and result. Compare attemptId before applying a delayed event.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "report.completed",
"data": {
"reportId": "report_example",
"attemptId": "attempt_example",
"status": "completed",
"code": null
}
}report.requires_action
Resume-to-job evidence needs a human mismatch review.
Receiver action: Surface a review-needed state and direct an authorised reviewer to the app. Do not automatically override it.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "report.requires_action",
"data": {
"reportId": "report_example",
"attemptId": "attempt_example",
"status": "requires_action",
"code": "CANDIDATE_JOB_MISMATCH"
}
}report.failed
An analysis reached terminal failure.
Receiver action: Read report status, retain the request/attempt identity, and review the supported retry path.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "report.failed",
"data": {
"reportId": "report_example",
"attemptId": "attempt_example",
"status": "failed",
"code": "ANALYSIS_FAILED"
}
}report.result_ready
A versioned resume evaluation was published.
Receiver action: Fetch the detailed report result and deduplicate by resource, attempt, and resultRevision.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "report.result_ready",
"data": {
"reportId": "report_example",
"attemptId": "attempt_example",
"resultRevision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
}report.deleted
A report was deleted.
Receiver action: Stop polling the report and apply your downstream deletion policy; 404 is expected.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "report.deleted",
"data": {
"reportId": "report_example"
}
}interview.invited
A new interview attempt was created.
Receiver action: Save interviewId and follow preparation and email delivery independently.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.invited",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": null
}
}interview.started
The candidate started the interview.
Receiver action: Mark candidate participation in progress for this attempt.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.started",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": null
}
}interview.completed
The candidate completed the conversation.
Receiver action: Check evaluation; completion does not guarantee the evaluation is ready.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.completed",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": null
}
}interview.expired
The invitation expired.
Receiver action: Stop treating the link as usable. Review whether the hiring team needs a new attempt.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.expired",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": null
}
}interview.preparation_failed
Interview content preparation failed.
Receiver action: Inspect the attempt and arrange recovery; do not tell the candidate preparation is ready.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.preparation_failed",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": null
}
}interview.result_ready
An interview evaluation was published.
Receiver action: Fetch the interview result and save its resultRevision.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.result_ready",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
}interview.result_failed
Interview evaluation failed.
Receiver action: Show evaluation unavailable; do not interpret this as a negative candidate outcome.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.result_failed",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": null
}
}interview.invitation_failed
Invitation email delivery failed.
Receiver action: Inspect delivery state and recipient details before an intentional resend.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "interview.invitation_failed",
"data": {
"reportId": "report_example",
"interviewId": "interview_example",
"resultRevision": null
}
}batch.completed
Every batch item reached the completion point for its kind.
Receiver action: Fetch item outcomes. Invitation completion means admission, not candidate completion; a batch can include failures.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "batch.completed",
"data": {
"batchId": "batch_example",
"succeeded": 2,
"failed": 1
}
}webhook.test
An Admin requested a receiver test.
Receiver action: Verify, deduplicate, and acknowledge it without starting candidate work.
{
"id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d",
"schemaVersion": 1,
"occurredAt": "2026-09-29T12:00:00.000Z",
"type": "webhook.test",
"data": {
"message": "ProBB webhook test"
}
}Missed and deleted events
Read retained events with events:read to recover notifications. The feed is ordered by durable publication; HTTP deliveries can still arrive out of order. Deleted bodies become minimal tombstones containing id, type, occurredAt, and deleted=true. A tombstone is an event-feed representation, not a new event type or a replacement webhook payload.
Use replay and catch-up for receiver redelivery. Events are retained for 30 days; reconcile current resource state if your cursor expires.