Assessments

📘

We recommend reading the Integration Plugins Overview first.

Overview

This documentation covers two components of the Integration Plugins Framework the createAssessment action workflow and the webhook processing mechanism. Together, these enable a complete integration cycle where the platform sends candidates to external assessment systems and receives status updates asynchronously.

Assessment Creation Flow

Lifecycle Overview

1. User initiates "Send to ExampleAssessments" action (where ExampleAssessments is the name of the assessments provider/service defined by the plugin configuration)

   
   
   

2. Pinpoint calls Action Meta Endpoint to build the form

3. User fills and submits the form

4. Platform calls Action Submit Endpoint to process

   1. The plugin calls the external system by passing the params from the form, webhook URL and redirect URL.
   2. External system (assessment provider) processes the request
      1. If the request is correct,
         1. The plugin should send a successful response with ID of the assessment from the external system.
         2. Pinpoint will then store the Assessment Record with ID of the assessment from the external system and request details.
         3. External system invites the candidate to perform the assessment (typically via email)
      2. If the external system rejects the request (validation errors, 5xx)
         1. The plugin should return an error response
         2. Pinpoint shows the errors on the form and allows the user to correct errors and submit again (go back to point 3)

5. User completes the assessment

6. External system sends webhook back to Pinpoint platform (using the webhook URL provided by the plugin)

7. Pinpoint calls Webhook Process Endpoint to process (parse) the webhook payload

   1. Plugin extracts data from the webhook payload and responds with a structured payload to update the Assessment record
   2. Pinpoint updates the Assessment record and sends notifications about completed assessment (if requested by the plugin)

📘

All requests Pinpoint makes to the plugin are POST requests

Example implementations

We find it best to learn by looking at examples. Please find 2 example working implementations to get an idea of what is involved.

Example FastAPI implementation:

https://github.com/dwedigital/pinpoint_assessment_plugin_provider

Example Express.js implementation

https://github.com/dwedigital/pinpoint_assessment_plugin_express_example

createAssessment Action

Purpose

The createAssessment action enables users to send candidate information to an external assessment provider. This creates an assessment record in both the platform and the external system. It also handles the webhook response from the external system, which updates the assessment record in the platform.

Initial Set Up Endpoint (Meta Endpoint)

Endpoint: Defined by your service (e.g. / )

Called when: You initiate the setup of your plugin service. Pinpoint calls this endpoint when it registers the plugin in the system to get the name, logo and possible actions and configurations fields. You can see it as a handshake between Pinpoint (Integration Plugins Framework) and the plugin.

Responsibilities:

• Create the integration in Pinpoint
• Fetch configuration fields
• Fetch form field data mappings

Response

Example Meta Response

{
          version: '1.0.0',
          name: 'ExampleAssessments',
          logoBase64: relative_base64_png('logo.png'),
          actions: [
            {
              key: 'createAssessment',
              label: 'Send to ExampleAssessments',
              iconSvgBase64: relative_base64_svg('action-logo.svg'),
              metaEndpoint: CREATE_ASSESSMENT_META_ENDPOINT,
              mappings: [
                { key: 'firstName', label: 'First Name', value: '{{candidate_first_name}}' },
                { key: 'lastName', label: 'Last Name', value: '{{candidate_last_name}}' },
                { key: 'email', label: 'Email', value: '{{{candidate_email}}}' },
                { key: 'cvDocument', value: '{{candidate_cv}}' },
              ],
            },
          ],
          webhookProcessEndpoint: WEBHOOK_PROCESS_ENDPOINT,
          webhookAuthenticationHeader: 'X-Verify',
          configurationFormFields: [
            {
              key: 'apiKey',
              label: 'API Key',
              description: "Your API key for ExampleAssessments. The correct key is #{CORRECT_API_KEY}",
              type: 'string',
              required: true,
              sensitive: true,
              useAsHttpHeader: 'X_EXAMPLE_ASSESSMENTS_KEY',
              placeholder: 'For example: uogKYdo4Foufve82P_*Mrpm7uu-bY2AwG7ur.usf',
            },
            {
              key: 'apiBaseUrl',
              label: 'Base URL',
              description:
                'Your Base URL for ExampleAssessments. Use `http://localhost:14568` if running local Sinatra server.',
              type: 'string',
              required: true,
              sensitive: false,
              useAsHttpHeader: 'X_EXAMPLE_BASE_URL',
              placeholder: 'For example: http://localhost:14568',
            },
            {
              key: 'mostRecentFirstName',
              label: 'Most Recent First Name',
              description:
                'The most recent first name that was successfully submitted, for persistence testing purposes',
              type: 'string',
              sensitive: false,
              placeholder: 'For example: Dave',
            },
          ],
        }

Meta response schema

Action Object Schema

Configuration Form Fields Schema

Mapping Object Schema

List Endpoint Object Schema

Action Meta Endpoint

Endpoint: Defined in the meta response (at actions.[].metaEndpoint, e.g. /createAssessment/meta)

Called when: User clicks the action button in the UI (e.g. Send to ExampleAssessment)

Responsibilities:

• Validate plugin configuration
• Fetch dynamic options from external API (e.g., available tests)
• Build the form fields

Dynamic form refetching

Plugins framework supports form re-rendering based on value selected by the user. Please find more information here

Response

Response Example

Return a form with all necessary fields:

{
  actionVersion: '1.0.0',
  key: 'createAssessment',
  label: 'Send to ExampleAssessments',
  description: 'Sends a candidate to the internal ExampleAssessments system',
  formFields: [
    {
      key: 'selectedTest',
      label: 'Selected Test',
      placeholder: 'Select test...',
      type: 'string',
      required: true,
      value: '',
      singleSelectOptions: options
    },
    {
      key: 'firstName',
      label: 'First Name',
      type: 'string',
      required: true,
      readonly: false,
    },
    {
      key: 'lastName',
      label: 'Last Name',
      type: 'string',
      required: true,
      readonly: false
    },
    {
      key: 'email',
      label: 'Email',
      type: 'string',
      required: true,
      readonly: false
    },
    {
      key: 'cvDocument',
      label: 'CV',
      type: 'file',
      required: false,
      readonly: false
    }
  ],
  submitEndpoint: CREATE_ASSESSMENT_SUBMIT_ENDPOINT
}

Response Schema

Form Fields Schema

Select Option Object Schema

Action Submit Endpoint

Endpoint: Defined in meta response (via submitEndpoint, e.g. /createAssessment/submit)

Called when: User submits the form

Responsibilities:

• Validate configuration and field values
• Send assessment creation/inivte request to external system
• Return success/error feedback

Payload

The platform sends several key pieces of data in the payload that can be used to facilitate some specific flows with third parties. Key fields are:

• formFields - Form field values submitted by the user - use this to generate payload for assessment creation in assessment provider
• configurationValues - Current configuration values from plugin setup (e.g. credentials)
• generatedUuid - Unique identifier for this assessment instance - this is different for every request
• generatedUuidRedirectUrl - URL to redirect candidates after assessment completion (to be shared with external system) - this is different for every request
• webhookUrl - URL where an external system should send status updates to (status change, assessment completion, etc) - this is the same for every request. If your third party requests specific webhook URLs for each record, you can build a specific URL in your provider adding the generatedUuid in the query parameters.

Example payload

{
  payloadVersion: '1.0.0',
  key: 'createAssessment',
  formFields: [
    { key: 'selectedTest', value: 'cognitive-test' },
    { key: 'firstName', value: 'Example' },
    { key: 'email', value: '[email protected]' }
  ],
  configurationValues: [
    { key: 'cvDocument', value: 'https://example.com/cv.pdf' }
  ],
  generatedUuid: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  webhookUrl: 'https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1',
  generatedUuidRedirectUrl: 'https://app.pinpointhq.xyz/integration_plugins/candidate_assessments/redirect/f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
}

Example Successful Response

{
  resultVersion: '1.0.0',
  key: 'createAssessment',
  success: true,
  assessmentName: 'Cognitive Assessment',
  status: 'pending',
  externalIdentifier: 'external-uuid-456',
  externalRecordUrl: 'https://api.example.com/api/external-uuid-456',
  message: 'Assessment was successfully sent to the candidate'
}

Example Error Response

{
  resultVersion: '1.0.0',
  key: 'createAssessment',
  success: false,
  toast: {
    error: 'Failed to send assessment to the candidate'
  },
  errors: {
    email: 'Email is invalid',
    firstName: 'First name is required',
    assessmentId: 'Assessment ID is required'
  }
}

Request Payload Schema

When the user submits the form, Pinpoint sends a POST request to your submit endpoint with the following payload structure:

Form Field Value Object

Configuration Value Object

Response Schema

Your endpoint must return a response following this schema:

Success Response

Error Response

If validation fails or the external system rejects the request, return:

Toast Object Schema

Field Error Object Schema

Persist Object Schema

The persist array allows storing values back to the plugin configuration. These values become available in subsequent API calls through configurationValues in the payload. It is a way to update a plugin configuration field(s) based on the response of an external system.

External Link Object Schema

Webhook Processing

Purpose

Webhooks enable external assessment systems to push status updates back to the platform asynchronously. This eliminates the need for polling and provides real-time updates.

The flow looks like this:

1. External system sends a POST request to the webhookUrl (which was sent in the payload to the submit endpoint and plugin sent it to the external system).
2. Plugins Framework receives the webhook, finds the plugin instance based on the ID in the webhookUrl responds with 200 OK and schedules the background job to process the webhook payload.
3. The framework's background job does the following:
   1. Sends a webhook request (with the original payload form the extrenal system) to the plugin's webhook endpoint.
   2. Plugin processes the webhook payload and returns a structured response which the framework uses to update the assessment record in the platform.
   3. The framework updates the assessment record in the platform with the parameters returned by the plugin and sends notifications to Pinpoint users (if requested).

Webhook Configuration

Define the webhook process endpoint in the meta response via webhookProcessEndpoint field.

Webhook Process Endpoint

Endpoint: Defined in meta response (e.g., /webhook/process)

Called when: External system POSTs to the platform's webhook URL

Responsibilities:

• Parse webhook payload
• Extract assessment updates
• Return structured update instructions

Payload

Example request payload

{
  "body": "{\"status\":\"completed\", \"id\":\"external-uuid-123\", \"assessmentName\":\"Cognitive Assessment\"}",
  "headers": {
    "Content-Type": "application/json"
  },
  "configurationValues": [
    {
      "key": "apiKey",
      "value": "apwu498roa9wejrfahow4u"
    }
  ]
}

Request Payload Schema

When an external system sends a webhook to Pinpoint, the platform forwards the request to your webhook process endpoint with this payload:

💡

The body field contains the raw webhook payload as a string. You'll need to parse it (e.g., JSON.parse(payload['body'])) to extract the data from your external assessment system.

Response

Example successful response

Response Schema

Your webhook process endpoint must return a response following this schema:

Update Assessment Object Schema

Each object in the updateAssessments array should follow this structure:

📘

Why this is an Array? Although webhooks typically update a single assessment, the array structure allows for batch updates in future implementations and provides consistency with other update patterns.

External Link Object Schema

Example of the webhook process logic

def self.webhook_process(payload:, headers: nil)
  api_base_url = headers&.dig(API_BASE_URL_HEADER)
  parsed_body = JSON.parse(payload['body'])
  
  *# Extract assessment data*
  external_guid = parsed_body['id']
  status = parsed_body['status'] if ALLOWED_STATUSES.include?(parsed_body['status'])
  detailed_status = parsed_body['detailed_status']
  score = parsed_body['score']
  report_path = parsed_body['report_path']
  report_url = "#{api_base_url}/#{report_path}"
  
  *# Build assessment update*
  assessment_update = {
    externalIdentifier: external_guid,  # Matches externalIdentifier from submit
    score: score,
    shouldNotify: true,  # Trigger platform notifications
    externalLinks: [
      { key: 'report', label: 'Report', url: report_url }
    ]
  }
  
  # Optional fields*
  assessment_update['status'] = status if status
  assessment_update['detailedStatus'] = detailed_status if detailed_status
  
  # Return array of updates (can update multiple assessments)
  {
    resultVersion: '1.0.0',
    success: true,
    updateAssessments: [assessment_update]
  }
end

External Links

External links appear in the platform UI as actionable buttons/links:

{
  key: 'report',           # Unique identifier
  label: 'View Report',    # Display text
  url: 'https://...'       # Destination URL
}

These allow users to quickly access related resources in the external system. This is typically used for assessment report URLs (link to PDF or assessment page in the external system).

Complete Integration Flow Example

Note: This is a simplified example of the complete flow (payloads are not complete).

1. User Sends Candidate to Assessment

Platform → Plugin (Action Meta Endpoint)

ruby

GET /createAssessment/meta

Plugin → Platform

ruby

{
  formFields: [
    { key: 'selectedTest', type: 'string', singleSelectOptions: [...] },
    { key: 'firstName', type: 'string', value: 'John' },
    { key: 'email', type: 'string', value: '[email protected]' }
  ],
  submitEndpoint: '/createAssessment/submit'
}

2. User Submits Form

Platform → Plugin (Submit Endpoint)

POST /createAssessment/submit
{
  formFields: [
    { key: 'selectedTest', value: 'cognitive-test' },
    { key: 'firstName', value: 'Example' },
    { key: 'email', value: '[email protected]' }
  ],
  generatedUuid: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  webhookUrl: 'https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1',
  generatedUuidRedirectUrl: 'https://app.pinpointhq.xyz/integration_plugins/candidate_assessments/redirect/f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
}

3. Plugin Creates Assessment

Plugin → External Assessment System

POST https://api.example.com/api/assessments
{
  name: 'Example Test',
  email: '[email protected]',
  webhook_url: 'https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1?uuid=81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  platform_url: 'https://app.pinpointhq.xyz/integration_plugins/candidate_assessments/redirect/f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  uuid: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
}

External System → Plugin

{
  id: 'external-uuid-456',
  status: 'pending',
  description: 'Cognitive Assessment'
}

4. Plugin Returns Success (or Error) Response

Plugin → Platform

{
  success: true,
  assessmentName: 'Cognitive Assessment',
  status: 'pending',
  externalIdentifier: 'external-uuid-456',
  externalRecordUrl: 'https://api.example.com/api/external-uuid-456',
  message: 'Assessment was successfully sent...'
}

5. Candidate Completes Assessment

External System → Platform (Webhook)

POST https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1
{
  id: 'external-uuid-456',
  status: 'completed',
  detailed_status: 'Scored 85/100',
  score: 85,
  report_path: 'reports/external-uuid-456'
}

6. Platform Processes Webhook

Pinpoint passes back the payload it receives at the webhook endpoint to the provider to carry out any custom logic and return a result to complete the assessment update

Platform → Plugin (Webhook Process)

POST /webhook
{
  body: '{"id":"external-uuid-456","status":"completed",...}'
}

Plugin → Platform

{
  success: true,
  updateAssessments: [
    {
      externalIdentifier: 'external-uuid-456',
      status: 'completed',
      score: 85,
      shouldNotify: true,
      externalLinks: [
        { key: 'report', label: 'Report', url: 'https://api.example.com/reports/...' }
      ]
    }
  ]
}