Webhooks

Rather than poll Report Status, supply a callbackUrl when assigning a candidate. Scout Select will POST a signed event to that URL once the report is ready (or fails to generate).

Unlike certifications, regular assessments have no human review/release gate - the report is considered final as soon as generation succeeds, so there's a single completion event rather than a multi-stage sequence.

Events

• assessment.completed - the report is ready. result is populated.
• assessment.failed - report generation errored. result is null.

Payload shape

{
  "eventId": "8f14e45f-...",
  "eventType": "assessment.completed",
  "occurredAt": "2026-07-24T09:41:03.120Z",
  "assessmentSessionId": "clv3c...",
  "externalReference": "your-internal-id-12345",
  "result": {
    "assessmentSessionId": "clv3c...",
    "overallScore": 7.5,
    "skillWiseScores": [
      {
        "label": "React",
        "score": 8,
        "concepts": [
          { "label": "Hooks", "score": 8 },
          { "label": "Rendering behavior", "score": 6 }
        ]
      }
    ],
    "communicationScores": [
      { "label": "Communication", "score": 8 },
      { "label": "Sentiment", "score": 7 },
      { "label": "Clarity", "score": 8 },
      { "label": "Conciseness", "score": 6 },
      { "label": "Fluency", "score": 8 },
      { "label": "Confidence", "score": 7 },
      { "label": "Consistency", "score": 7 }
    ]
  }
}

For assessment.failed, result is null.

See Report Status for the meaning of each result field - it's the exact same shape returned there.

Verifying the signature

Every callback carries an x-scout-signature header of the form sha256=<hex-hmac>, computed as HMAC-SHA256(rawRequestBody, yourWebhookSigningSecret) - the same signing secret tied to the API key used to assign the candidate (see Authentication). Verification works identically to the certification webhook.

Delivery notes

• Requests time out after 10 seconds on Scout Select's side. Unlike the initial rollout of the certification webhook, failed deliveries are retried: up to 5 attempts with exponential backoff (roughly 1 min, 5 min, 30 min, 2 hr, then 12 hr after each failure) before being marked permanently failed. Keep polling Report Status as a fallback for critical flows regardless.
• Deduplicate on eventId - a retried delivery reuses the same eventId as its original attempt.
• If your organization has configured an allowed webhook domains list, callbackUrl must match one of the allowed hostnames or the assign mutation is rejected upfront.