Overview

All webhook requests sent by Begini include a signature that allows you to verify that the request is authentic.

This signature is generated using HMAC and your API key.

By verifying this signature, you can ensure that:

• The request was sent by Begini
• The payload has not been altered
• The data can be trusted

---

Why HMAC verification matters

Without verification, your webhook endpoint could accept:

• Forged requests
• Malicious payloads
• Tampered data

HMAC verification protects your system from these risks.

---

How it works

When Begini sends a webhook:

1. The JSON payload is generated
2. A hash is created using your API key
3. The hash is sent in the X-Signature header

Your system must:

1. Recreate the hash using the received payload
2. Compare it with the X-Signature value
3. Accept the request only if they match

---

Request structure

Each webhook request includes:

Header

X-Signature: <HMAC_SIGNATURE>
Content-Type: application/json

Body

• JSON payload (event data)

---

Verification process

Step 1: Receive the raw payload

You must use the raw request body exactly as received.

Do not:

• Reformat JSON
• Change spacing
• Modify encoding

Any change will result in a different hash.

---

Step 2: Generate HMAC hash

Use your API key as the secret to generate a hash from the payload.

Example (Python):

importhmac
importhashlib

defgenerate_signature(payload,api_key):
returnhmac.new(
api_key.encode(),
payload.encode(),
hashlib.sha256
    ).hexdigest()

---

Step 3: Compare signatures

Compare the generated signature with the value from X-Signature.

Example:

defverify_signature(received_signature,payload,api_key):
expected_signature=generate_signature(payload,api_key)
returnhmac.compare_digest(received_signature,expected_signature)

---

Step 4: Accept or reject request

• If signatures match → process webhook
• If not → reject request

---

Example flow

1. Webhook received
2. Extract X-Signature
3. Read raw request body
4. Generate HMAC using API key
5. Compare signatures
6. Continue processing if valid

---

Common mistakes

• Using parsed JSON instead of raw payload
• Using the wrong API key (sandbox vs production)
• Incorrect hashing algorithm
• Not using constant-time comparison
• Ignoring signature validation entirely

---

Best practices

• Always validate signatures before processing
• Use secure comparison methods (compare_digest)
• Log failed verification attempts
• Separate sandbox and production verification keys
• Reject all unverified requests

---

Failure handling

If verification fails:

• Return a non-200 response
• Do not process the payload
• Log the event for investigation

---

Relationship to other security components

HMAC verification works alongside:

• API Authentication Guide
• Webhooks Overview
• Security Best Practices

---

Next steps

To complete your webhook setup:

• Webhooks Overview
• Webhook Payload Structure
• Security Best Practices