Overview

This guide covers common issues that can occur when receiving and processing Begini webhooks.

Most webhook issues are related to endpoint configuration, request handling or payload validation rather than problems with the Begini platform itself.

---

Webhooks not being received

Issue

Your system is not receiving any webhook requests.

Common causes

• Incorrect or missing webhook endpoint configuration
• Endpoint is not publicly accessible
• DNS or networking issues
• Environment mismatch (test vs production)

How to fix

• Verify the webhook endpoint URL is correct
• Ensure the endpoint is publicly accessible (not behind a firewall or local network)
• Test the endpoint using external tools
• Confirm the correct environment is being used

---

Endpoint returning non-200 response

Issue

Webhooks are sent but not successfully accepted.

Common causes

• Endpoint returning an error status code
• Validation or parsing errors
• Internal application errors

How to fix

• Ensure your endpoint returns HTTP 200 on success
• Log incoming requests and responses
• Handle payload parsing errors gracefully
• Return meaningful error responses for debugging

---

Signature verification failing

Issue

HMAC verification fails and requests are rejected.

Common causes

• Incorrect webhook secret
• Payload modified before hashing
• Incorrect hashing implementation
• Using parsed JSON instead of raw body

How to fix

• Use the exact raw request body for signature generation
• Confirm the correct secret key is being used
• Validate the hashing algorithm and implementation
• Compare signatures using a constant-time method

---

Payload parsing errors

Issue

Your system cannot read or process the webhook payload.

Common causes

• Invalid JSON handling
• Incorrect assumptions about payload structure
• Missing fields or unexpected formats

How to fix

• Ensure your endpoint accepts application/json
• Validate JSON before processing
• Handle optional or missing fields safely
• Avoid strict assumptions about field presence

---

Incorrect event handling

Issue

Your system processes webhooks incorrectly or triggers the wrong actions.

Common causes

• Not checking event.type
• Treating all events the same
• Misinterpreting application vs score events

How to fix

• Always check the event.type field
• Handle each event type explicitly
• Separate logic for:

---

Duplicate webhook events

Issue

The same webhook event is processed multiple times.

Common causes

• Webhook retries due to failed delivery
• Network timeouts
• Delayed responses from your endpoint

How to fix

• Implement idempotency in your system
• Use uid and/or session identifiers to track processed events
• Ignore duplicate events once processed

---

Events arriving out of order

Issue

Webhook events do not arrive in the expected sequence.

Common causes

• Network delays
• Retry behaviour
• Parallel processing

How to fix

• Do not rely on strict ordering of events
• Use timestamps (epoch values) to determine sequence
• Design your system to handle events independently

---

Missing or unexpected data

Issue

Webhook payload does not contain expected fields.

Common causes

• Different event types have different structures
• Optional fields not present