Overview

When a webhook is triggered, Begini sends a structured JSON payload to your endpoint.

This payload contains all the information required to identify the session, understand the result and process it within your system.

Understanding the payload structure is essential for integrating Begini into automated workflows.

---

Payload format

Webhook payloads are sent as JSON in an HTTP POST request.

A typical payload includes:

• Event metadata
• Session identifiers
• Assessment results
• Supporting data and insights

---

Example payload

Below is a simplified example of a webhook payload:

{
  "event":"assessment.completed",
  "timestamp":"2026-01-01T12:00:00Z",
  "data": {
    "integration_id":"INT-12345",
    "unique_id":"USER-67890",
    "session_id":"SESSION-abc123",
    "risk_score":0.32,
    "trust_score":0.87,
    "status":"completed",
    "completion_time_seconds":185,
    "traits": {
      "risk_taking":0.45,
      "consistency":0.78,
      "attention":0.66
    }
  }
}

This example is for illustration purposes. Your actual payload may vary depending on your deployment and configuration.

---

Top-level fields

event

Identifies the type of event that triggered the webhook.

Example:

• assessment.completed

---

timestamp

The time at which the event occurred.

This can be used for logging, ordering and debugging.

---

data

Contains the main payload related to the event.

This includes identifiers, results and behavioural outputs.

---

Key data fields

integration_id

Identifies your Begini integration.

Used to distinguish between different environments or configurations.

---

unique_id

Your internal identifier for the user or application.

This is critical for linking results back to your system.

---

session_id

A unique identifier for the assessment session.

Useful for tracking and debugging individual assessments.

---

risk_score

The behavioural risk score generated from the assessment.

Used for decisioning and segmentation.

---

trust_score

Indicates the reliability of the session data.

Helps determine how much confidence to place in the result.

---

status

Indicates the state of the assessment.

Example:

• completed

---

completion_time_seconds

Time taken for the user to complete the assessment.

Can be used as part of behavioural or operational analysis.

---

traits (if enabled)

Provides additional behavioural insights.

These may include indicators related to:

• Risk behaviour
• Consistency
• Attention
• Decision patterns

---

Handling the payload

When your system receives a webhook:

1. Validate the request (see security section)
2. Parse the JSON payload
3. Extract key fields (e.g. unique_id, risk_score)
4. Map the data to your internal system
5. Trigger any required actions

---

Idempotency and duplicates

Webhook events may be delivered more than once.

Your system should:

• Detect duplicate events
• Avoid processing the same session multiple times
• Use session_id or event identifiers for tracking

---

Error handling

Your endpoint should:

• Return a successful response (e.g. HTTP 200) when processed
• Log failed or malformed payloads
• Retry handling internally if needed

If your endpoint does not respond successfully, webhook delivery may be retried.

---

Extensibility

The payload structure may evolve over time as new features or data points are added.

Your implementation should:

• Be tolerant to additional fields
• Avoid strict dependencies on unused fields
• Focus on the fields required for your use case

---

Best practices