Overview

Use this guide to diagnose and fix webhook issues. Most problems fall into one of a few categories — endpoint configuration, HMAC verification, or environment mismatch. Work through the relevant section and escalate to Begini support if the issue persists.

---

No webhooks being received

Check first: is your webhook endpoint URL configured in Beacon → Deployment Centre → correct environment tab?

Other causes:

• Endpoint is not publicly accessible (behind a firewall or localhost)
• DNS not resolving correctly
• Using Test credentials but checking a Production endpoint (or vice versa)

Use the test API (POST /v1/webhooks-management/test) to confirm delivery — a 503 response means Begini cannot reach your endpoint at all.

---

Test API returns 424

Your webhook endpoint is not configured for this deployment. Go to Beacon → Deployment Centre → select deployment → Test or Production tab → set the Webservice Endpoint URL.

---

Endpoint returns non-200 / test API returns 422

Begini reached your endpoint but it returned an error. The 422 response body includes the status code your endpoint returned and its response body — check those for the root cause. Common issues:

• HMAC verification failing (see below)
• JSON parsing error in your receiver
• Unhandled exception in your webhook handler
• Your endpoint returning 201 or no content instead of 200

---

HMAC verification failing

Cause	Fix
Parsing JSON before hashing	Use the raw request body bytes — do not parse first
Wrong API key (Test vs Production)	Confirm you are using the key matching the environment
Wrong hashing algorithm	Must be HMAC SHA-512 hexdigest
Using == instead of compare_digest	Switch to hmac.compare_digest

---

Receiving duplicate events

Begini retries delivery when your endpoint does not respond with 200 (including on timeouts). Your handler should be idempotent — use uid + event.type + the relevant timestamp to detect and ignore duplicates.

If you are seeing unexpected duplicates outside of retries, check that your endpoint is not processing the same request more than once internally.

---

Events arriving out of order

Do not assume events arrive in sequence. A psychometric_score.complete may arrive before application.complete under some conditions. Use event timestamps to determine order, not arrival time.

---

Score events not arriving

Confirm the assessment was fully completed by checking the results screen in Beacon. An application.complete event without a subsequent score event usually means scoring is still in progress — scores are not always immediate. If the score event never arrives after a reasonable period, contact Begini support with the uid and integration_id.

---

Webhooks working in Test but not Production

• Confirm the Production webhook endpoint is configured (separate from Test)
• Confirm you are using Production API key for HMAC verification in production
• Check your production server is accessible and returning 200

---

When to escalate

Collect the following before contacting support:

• uid and integration_id of the affected session
• Event type expected
• Timestamp of the issue
• Your endpoint's response code and body
• Whether the test API reproduces the issue

Next steps

• Testing Webhooks — use the test API to validate your endpoint
• Operations Troubleshooting — broader operational issue guide