Skip to main content

Deep Dive: Scorpion App Webhooks

Donovan Allen
Updated

Deep Dive: Scorpion App Webhooks

This updated version includes explicit triggers for every webhook event and example payloads so that external teams do not need to guess or make assumptions.

Shape

1. What Webhooks Are

A webhook is a callback URL that Scorpion sends event data to whenever something important happens.

Your system must: 

  • Host a URL that accepts HTTPS POST requests
  • Receive JSON
  • Validate and process incoming events

Shape

2. Where to Configure Webhooks

Webhooks are configured inside your Scorpion App’s Integrations area.

  1. Navigate to https://scorpion.caveon.com/apps/<app_id>/settings
  2. Scroll to Integrations → Webhooks.
  3. Webhook Configuration:  
  4. From your apps page, scroll to Hooks → Add a Hook

5. Select your webhook event from the Add a Hook dropdown modal and enter your URL you wish to send this webhook event to, then click the green Add Hook button.

6. Your webhook will now appear under the Hooks section in your app page.

Shape

3. Webhook Payload Structure

All webhook events send JSON using this general structure:

{ 
  "event": "<event_type>", 
  "exam_id": "<exam_id>", 
  "delivery_id": "<delivery_id>" 
}

Additional fields vary by event.

Shape

4. Event Types, Triggers, and Example Payloads

Below is a complete list of webhook event types, exactly what triggers them, and sample payloads.
 

4.1 Delivery Webhooks (Most Common)

Delivery events fire when something happens to an individual exam delivery.

delivery_created

Trigger: A new delivery instance is created for a candidate.

{ 
  "event": "delivery_created", 
  "exam_id": "exam_123", 
  "delivery_id": "deliv_001" 
}
 

delivery_started

Trigger: A candidate launches the delivery and begins the exam.

{ 
  "event": "delivery_started", 
  "exam_id": "exam_123", 
  "delivery_id": "deliv_001" 
}
 

delivery_submitted

Trigger: A candidate submits answers (before scoring completes).

{ 
  "event": "delivery_submitted", 
  "exam_id": "exam_123", 
  "delivery_id": "deliv_001" 
}
 

delivery_completed

Trigger: The delivery reaches a final state—scoring is complete or the delivery is otherwise finalized.

{ 
  "event": "delivery_completed", 
  "exam_id": "exam_123", 
  "delivery_id": "deliv_001" 
}
 

delivery_rescored

Trigger: An administrator triggers rescoring.

{ 
  "event": "delivery_rescored", 
  "exam_id": "exam_123", 
  "delivery_id": "deliv_001" 
}
 

delivery_suspended

Trigger: Delivery is placed into a suspended/paused state.

{ 
  "event": "delivery_suspended", 
  "exam_id": "exam_123", 
  "delivery_id": "deliv_001" 
}
 

delivery_connected

Trigger: Candidate reconnects to proctoring/monitoring session.
 

delivery_disconnected

Trigger: Candidate loses connection.
 

delivery_settings_updated

Trigger: A delivery’s configuration (time limit, accommodations, etc.) is updated.

Shape

4.2 Exam Webhooks

Exam-level events fire when the structure or metadata of an exam changes.

exam_settings_updated

Trigger: Any exam configuration is modified.
 

exam_stats_updated

Trigger: Statistical calculations update (e.g., p-values, KR-20).

Shape

4.3 Export Webhooks

export_data

Trigger: A data export job completes.

{ 
  "event": "export_data", 
  "export_id": "exp_987", 
  "exam_id": "exam_123" 
}

Shape

4.4 File Webhooks

file_created

Trigger: Any file is uploaded or generated (images, attachments, exports, results, etc.).
 

file_deleted

Trigger: A file is removed.

Shape

4.5 Form Webhooks

form_created

Trigger: A new form is created.
 

form_updated

Trigger: A form’s configuration is modified.
 

form_versioned

Trigger: A new version of a form is published.
 

form_live_version_changed

Trigger: The live form assignment is changed.

Shape

4.6 Item Webhooks

item_created

Trigger: A new item is created in the item bank.
 

item_updated

Trigger: Any change to item metadata or content.
 

item_versioned

Trigger: A new version of an item is published.
 

item_live_version_changed

Trigger: The version assigned as “live” changes.
 

item_comment_created

Trigger: A reviewer leaves an item comment.

Shape

4.7 Role Webhooks

role_created

Trigger: A new role is created or assigned.
 

role_deleted

Trigger: A role is removed.

Shape

4.8 Shared Content Webhooks

shared_content_created

Trigger: A new shareable content object is created.
 

shared_content_deleted

Trigger: Shared content is removedShape
 

5. Summary

This expanded documentation now includes explicit triggers for each webhook and real JSON payload examples, reducing ambiguity for external partners and making integrations more reliable.

 

Related Articles: 

 

 

Related articles

Comments

0 comments

Please sign in to leave a comment.