Overview

To ensure webhook data is authentic and has not been tampered with, Begini supports webhook verification using HMAC signatures.

This allows your system to verify that incoming webhook requests genuinely originate from Begini and that the payload has not been altered in transit.

---

Why webhook security matters

Without verification, your webhook endpoint could:

• Accept forged or malicious requests
• Process incorrect or manipulated data
• Trigger unintended actions in your system

HMAC verification ensures that only trusted webhook events are processed.

---

How HMAC verification works

When Begini sends a webhook:

1. The payload is generated
2. A signature is created using a shared secret key
3. The signature is included in the request headers
4. Your system recalculates the signature
5. The two signatures are compared

If they match, the request is valid.

If they do not match, the request should be rejected.

---

What you need to implement

To verify webhook requests, your system must:

• Store your webhook secret securely
• Read the raw request body
• Extract the signature from the request headers
• Generate a hash using the same algorithm
• Compare the generated signature with the received signature

---

Signature header

Webhook requests include a signature header.

Example:

X-Begini-Signature: <generated-signature>

This header contains the HMAC hash generated by Begini.

---

Verification process (high level)

1. Receive the webhook request
2. Extract the raw request body
3. Retrieve the signature from the header
4. Generate your own HMAC hash using the shared secret
5. Compare both values

Only proceed if the values match.

---

Important implementation details

Use the raw request body

Do not modify or parse the payload before generating the hash.

Even small changes (such as whitespace or formatting) will produce a different signature.

---

Use a constant-time comparison

To avoid timing attacks, use a constant-time comparison method when comparing signatures.

---

Protect your secret

• Store your webhook secret securely
• Do not expose it in client-side code
• Rotate it if it is ever compromised

---

Handling failed verification

If signature verification fails:

• Reject the request (e.g. return HTTP 401 or 403)
• Do not process the payload
• Log the घटना for investigation

---

Combining security measures

HMAC verification should be used alongside:

• HTTPS endpoints
• IP restrictions (if applicable)
• Rate limiting
• Logging and monitoring

This creates a more robust security posture.

---

Common mistakes to avoid

• Parsing or modifying the payload before verification
• Using the wrong secret key
• Ignoring failed verification checks
• Logging sensitive data (such as secrets)

---

Best practices

• Verify every webhook request
• Fail securely (reject invalid requests)
• Log verification results for debugging
• Keep your implementation simple and reliable

---

Next steps

To validate your webhook implementation:

• Testing Webhooks
• Webhook Troubleshooting