Overview

This guide covers the most common operational issues encountered when running Begini in a live or test environment. Issues are grouped by the component where the failure is occurring — work through the relevant section, confirm the fix, and escalate to Begini support if the problem persists after following the steps below.

Sessions not being created (API)

Symptoms: API returns an error when calling the session endpoint.

Error	Likely cause	Fix
401	Missing or invalid api-key header	Check the api-key header is present and correct
403	API key not authorised for this integration	Confirm you are using the key for the correct deployment and environment
422	Invalid request body	Check uid (5–60 alphanumeric chars) and integration_id are both present and correct

Also confirm you are using Test credentials for Test and Production credentials for Production — they are not interchangeable.

---

No results received via webhook

Symptoms: sessions are created and assessments completed, but no data arrives in your system.

Check:

• Is the webhook endpoint configured in Beacon → Deployment Centre → correct environment tab?
• Is the endpoint publicly accessible over HTTPS?
• Use the test API (POST /v1/webhooks-management/test) — a 503 means Begini cannot reach your endpoint; a 424 means no endpoint is configured

See Testing Webhooks for the full test API reference and response codes.

---

Webhook delivery failures

Symptoms: webhooks are received but rejected, or the test API returns 422.

Check:

• Is your HMAC verification logic using the raw request body (not parsed JSON)?
• Are you using the correct API key for the environment?
• Is your endpoint returning HTTP 200 on success?

See Securing Webhooks (HMAC) and Webhook Troubleshooting for detailed diagnosis.

---

Scores missing or not appearing

Symptoms: application.complete received but no score event follows.

Score events are generated after processing completes — there may be a short delay after application.complete. If no score event arrives within a reasonable period, check:

• Was the assessment fully completed by the user?
• Is the psychometric_score.complete event type being handled in your receiver?
• Is your receiver filtering or dropping events silently?

If the issue persists, contact Begini support with the affected uid and integration_id.

---

Link generator issues

Symptoms: links not working or users unable to access the assessment.

Check:

• Is the correct deployment selected when generating links?
• Have the links expired? Links are tied to session time limits
• Are the links being distributed correctly without modification?

Fix: regenerate links and test one end-to-end before distributing.

---

Results visible in Test but not Production

Symptoms: everything works in Test but Production results are missing or behaving differently.

Check:

• Production webhook endpoint configured separately from Test?
• Production redirect URLs set?
• Integration code using Production API key and Integration ID?
• Viewing the Production tab (not Test) in Beacon results?

All environment configuration is independent — anything set in Test must be explicitly replicated in Production.

---

Access and permission issues

Symptoms: users cannot log in to Beacon or cannot see certain features.

Fix: review user roles in Beacon → profile dropdown → manage team. Admins have full access; viewers have read-only access. If a user has not received their invitation email, re-send it from the same menu. Invitation links expire after 24 hours.

---

Debugging approach

When troubleshooting any issue:

1. Identify which component is failing (session creation, assessment delivery, webhook receipt, scoring, Beacon display)
2. Check logs at each step
3. Reproduce in the Test environment where possible
4. Isolate the failing component before contacting support

When to escalate

Collect the following before contacting Begini support:

• Affected uid and integration_id
• Environment (Test / Production)
• Timestamp of the issue
• Steps to reproduce
• Relevant error codes or log output

Next steps

• Webhook Troubleshooting — diagnose webhook delivery issues
• Assessment Troubleshooting — diagnose assessment-specific issues
• Common Setup Issues & Fixes — quick fixes for common setup problems