Webhook Encryption & Decryption Guide

This guide explains how encrypted payloads are delivered, how to decrypt them, and what keys are required.

📘

Encryption is only available once enabled on your merchant profile.

When Is Encryption Applied?

Webhook encryption is enabled per webhook in your Merchant Portal. Once active:

1. Go to Settings → Integrations → Webhooks.

2. Click New or Edit.

3. Provide the destination URL, then add:

   • Header Key: X-Webhook-Secret
   • Header Value: Your generated Secret Key (32-character ASCII)

4. Click Update.

Encryption Algorithm

Decryption Steps (Developer Flow)

When you receive a webhook:

1. Decode the Base64 string.

2. Extract the first 16 bytes → this is your IV.

3. Decrypt the rest using:

   • AES-256 CBC
   • PKCS5 Padding
   • Your unique Secret Key

4. Parse the resulting plaintext → JSON object.

Here’s a typical decrypted body:

🖼️ [Insert “Decrypted JSON Body” image]

{
  "eventId": "1234",
  "eventName": "ORDER_CLOSED",
  "order": { ... },
  "invoice": { ... },
  "outletId": "abc-123"
}

Secret Key Requirements

Each webhook has its own secret key, viewable and manageable in the portal.

Requirements:

• Exactly 32 ASCII characters
• Must include letters, digits, and symbols
• Cannot be repeated characters
• No whitespace allowed
• Must be trimmed before use

Example of a valid key:

f9K@82nNc%P!r4QwLxTzA#10UvM&b6Xe

Best Practices

• Use HTTPS for your webhook URL.
• Secure your decryption logic and secret keys.
• Return a 200 OK to acknowledge webhook receipt.
• Log webhook failures and retry attempts.

Questions?

If you're unsure how to decrypt, reach out to your integration team.

Check out our guide on consuming webhooks.