Overview

Begini delivers results and events to your system in real time via webhooks. When something happens — a user completes an assessment, a score is generated, a session expires — Begini sends an HTTP POST request to your configured endpoint with a JSON payload describing the event.

This is the primary mechanism for receiving data in a production integration. Polling is not supported.

How it works

1. You configure a webhook endpoint URL in the Deployment Centre for each environment
2. A user goes through the assessment journey
3. Events are triggered as the journey progresses
4. Begini POSTs a JSON payload to your endpoint for each event
5. Your system processes the payload and returns HTTP 200

A single user journey can generate multiple events — for example, application.complete followed by psychometric_score.complete. Your system must handle each event independently.

Event types

Begini generates two categories of event:

Score completion events — triggered when a score result is ready. These are the primary events used for decisioning:

• psychometric_score.complete
• android_score.complete
• ios_score.complete

Application journey events — describe the state of the user's progress:

• application.complete
• application.expired
• application.incomplete
• application.cancelled

For full payload structures and examples, see Webhook Payload Structure & Event Types.

Endpoint requirements

Your webhook receiver must:

• Be publicly accessible over HTTPS
• Accept HTTP POST requests
• Handle Content-Type: application/json
• Return HTTP 200 promptly on success
• Process heavy logic asynchronously — acknowledge receipt first, then process

Security

Every webhook request includes an X-Signature header containing an HMAC SHA-512 signature of the payload, generated using your API key. You must verify this on every request before processing. See Securing Webhooks (HMAC) for implementation details.

Reliability and duplicates

Begini will retry delivery if your endpoint does not return HTTP 200. Your system should be idempotent — processing the same event twice should not cause problems. Use uid and event timestamps to detect and safely ignore duplicates.

Configuring your endpoint

Webhook endpoints are configured per deployment and per environment in Beacon → Deployment Centre → select deployment → Test or Production tab → Webservice Endpoint. Test and Production endpoints must be configured separately.

Next steps

• Webhook Payload Structure & Event Types — full payload reference for all event types
• Securing Webhooks (HMAC) — implement signature verification
• Testing Webhooks — validate your endpoint before going live