Webhooks

A webhook is a URL on your side that Deeper Signals calls with an HTTP POST and a JSON body when something happens on your account. Use webhooks instead of polling to learn when someone has completed an assessment.

Setup

1. Webhooks are a feature Deeper Signals enables per account. Ask your customer success contact if you do not see them.
2. An account administrator registers the URL in the admin app under Settings → Integrations → Webhooks. Up to 5 webhooks per account.
3. Each webhook can be limited to specific events and specific user groups. Leaving either empty means "all".

Your endpoint must accept POST with Content-Type: application/json over HTTPS and answer with any 2xx status.

Events

event	When
UserCreated	A user was created on the account, by any means (admin app, API, SSO, SCIM, CSV import, campaign).
UserDeleted	A user was deleted.
AssignedAssessmentFinished	A user completed an assessment. The payload includes the scores.

UserCreated and UserDeleted

{
  "event": "UserCreated",
  "id": 15768,
  "email": "jane.doe@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "created_at": "2026-10-01 14:42:42",
  "account": { "name": "Example Corp", "index_name": "examplecorp" }
}

UserDeleted has the same shape with "event": "UserDeleted". Store id: it is the ds_id you can later send in an SSO JWT and the {user_id} of every user endpoint.

AssignedAssessmentFinished

{
  "event": "AssignedAssessmentFinished",
  "id": 28663,
  "full_name": "Jane Doe",
  "email": "jane.doe@example.com",
  "employee_id": "EMP-1042",
  "groups": ["sales"],
  "company": "N/A",
  "country": "N/A",
  "ethnicity": "Prefer not to say",
  "locale": "en",
  "age": "N/A",
  "gender": "N/A",
  "account": { "name": "Example Corp", "indexName": "examplecorp" },
  "assessment": {
    "name": "Core Drivers",
    "id": 49344,
    "assessment_library_id": 24,
    "status": "completed",
    "retake": false,
    "score_type": "core_drivers_leadership",
    "user_reports": [
      { "assigned_user_report": { "id": 33005, "userReportName": "Core Drivers Pro" } }
    ]
  },
  "scales": {
    "Drive": 74.83,
    "Drive//Leading": 72.54,
    "Drive//Confident": 79.94,
    "Openness": 38.26,
    "Openness//Artistic": 30.44,
    "Stability": 43.06,
    "Extraversion": 36.8,
    "Agreeableness": 34.86,
    "Conscientiousness": 11.43,
    "Candid": 65.14,
    "Driven": 74.83
  }
}

• id is the user id; assessment.id is the id of this user's assessment instance; assessment.assessment_library_id identifies the assessment product (see GET /assessment_libraries).
• scales contains the scores. Keys are scale names; Parent//Child keys are sub-scales. Scales differ per assessment: the example above is Core Drivers. Use score_type to know which set to expect.
• assessment.user_reports lists the reports the user can see for this assessment. Use assigned_user_report.id with POST /share/v2/token/user-report/{locale} or the PDF endpoints to fetch the report.

Delivery

• One POST per webhook per event, sent from a background worker shortly after the event.
• There is no signature header today. Protect your endpoint by keeping the URL unguessable (for example include a long random path segment) and validating account.index_name.
• If your endpoint is down the delivery is not retried. Fetch the current state with GET /users/{user_id}/assessments or GET /users/{user_id}/results when you recover.
• Reply quickly (2xx within a few seconds) and process the payload asynchronously.

Testing

Point a webhook at a request-capture service, create a user through POST /user and watch UserCreated arrive. For AssignedAssessmentFinished, complete an assessment with a test user on the platform.