How to Retrieve Exam Deliveries Using the delivery_completed Webhook

Overview

This article explains how to retrieve (GET) a completed exam delivery from the Scorpion API when your system receives the delivery_completed webhook event.

This pattern is the recommended and supported approach for accessing finalized delivery data, including completed scoring.

Integration Flow (High Level)

1. A candidate completes an exam delivery.
2. Scorpion sends a delivery_completed webhook to your system.
3. Your system extracts the exam_id and delivery_id from the webhook payload.
4. Your system calls the Scorpion Get Delivery by ID endpoint.

This ensures delivery data is retrieved only after the delivery is finalized.

Prerequisites

Before implementing this integration, ensure you have:

• A Scorpion App with Read (GET) Delivery permissions
• A webhook endpoint capable of receiving HTTPS POST requests
• Your App’s Basic Authorization Token
• The Scorpion API base URL: https://scorpion.caveon.com

Webhook Event: delivery_completed

What Triggers This Event

The delivery_completed webhook fires when a delivery reaches a final state, meaning:

• The candidate has submitted the exam
• Scoring has completed or the delivery has otherwise been finalized

Important
This is the correct webhook to use when you need final results or delivery state. Earlier delivery events may return incomplete or unscored data.

Example Webhook Payload

All delivery webhooks use a consistent JSON structure. A delivery_completed payload looks like this:

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

Fields used to retrieve the delivery:

• exam_id
• delivery_id

Get Delivery by ID Endpoint

Endpoint

Use the IDs provided in the webhook payload to call the following endpoint:

GET https://scorpion.caveon.com/api/exams/<exam_id>/deliveries/<delivery_id>

This endpoint returns the full delivery record for the completed exam attempt.

Authentication & Headers

Authentication is handled using your App’s Basic Authorization Token.

Required headers:

Authorization: Basic <YourBasicAuthToken>
Content-Type: application/json

Step-by-Step Implementation

Step 1: Configure the Webhook

1. Navigate to: https://scorpion.caveon.com/apps/<app_id>/settings
2. Go to Integrations → Webhooks
3. Add a webhook for the delivery_completed event
4. Enter your HTTPS webhook URL

Step 2: Receive and Validate the Webhook

Your webhook endpoint should:

• Accept HTTPS POST requests
• Parse the incoming JSON payload
• Confirm the event type is delivery_completed

At minimum, extract:

• exam_id
• delivery_id

Step 3: Retrieve the Delivery

Use the extracted IDs to issue a GET request to the Scorpion API.

Example cURL Request

curl --request GET \
  --url "https://scorpion.caveon.com/api/exams/<exam_id>/deliveries/<delivery_id>" \
  --header "Authorization: Basic <BasicToken>" \
  --header "Content-Type: application/json"

Common Use Cases

Customers typically retrieve deliveries after delivery_completed to:

• Access final scores and pass/fail outcomes
• Sync results into an LMS, HR system, or CRM
• Trigger certificate issuance or credit assignment
• Archive finalized delivery records for auditing

Best Practices

• Only retrieve deliveries after delivery_completed to avoid partial data
• Treat webhooks as event notifications, not data payloads
• Log webhook payloads and API responses for traceability
• Implement retry logic for GET requests
• Secure your webhook endpoint appropriately

Summary

The delivery_completed webhook is the authoritative signal that an exam delivery is finalized. By pairing this webhook with the GET /exams/{exam_id}/deliveries/{delivery_id} endpoint, you can reliably retrieve completed delivery data and integrate Scorpion exam results into downstream systems.

This approach aligns with Scorpion best practices and ensures accurate, complete delivery data.