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)
- A candidate completes an exam delivery.
- Scorpion sends a
delivery_completedwebhook to your system. - Your system extracts the
exam_idanddelivery_idfrom the webhook payload. - 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_iddelivery_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
- Navigate to:
https://scorpion.caveon.com/apps/<app_id>/settings - Go to Integrations → Webhooks
- Add a webhook for the
delivery_completedevent - 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_iddelivery_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_completedto 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.
Comments
0 comments
Please sign in to leave a comment.