Download the PHP package olmed/databus-webhook-helpers without Composer

Olmed DataBus Webhook Helpers

A PHP library for secure webhook payload encryption, decryption and verification using AES-256-CBC encryption and HMAC-SHA256 signatures.

Requirements

• PHP >= 7.0
• OpenSSL extension
• JSON extension

Installation

Install via Composer:

Usage

Basic Example

Complete Webhook Endpoint Example

How It Works

Encryption Format

The payload is encrypted using AES-256-CBC with the following structure:

1. A random 16-byte Initialization Vector (IV) is generated
2. The data is encrypted using AES-256-CBC
3. The IV is prepended to the encrypted data
4. The combined data (IV + encrypted) is base64-encoded

Verification Process

1. The base64 payload is decoded
2. The IV (first 16 bytes) is extracted
3. The remaining data is decrypted using AES-256-CBC
4. A JSON structure is reconstructed: {"guid":"...","webhookType":"...","webhookData":{...}}
5. An HMAC-SHA256 signature is computed for this JSON
6. The computed signature is compared with the provided signature

Security Features

• AES-256-CBC encryption - Industry-standard encryption
• HMAC-SHA256 signatures - Prevents tampering and ensures authenticity
• Timing-attack safe comparison - Uses hash_equals() for signature verification
• 32-byte keys required - Enforces strong key lengths

Key Generation

To generate secure 32-byte keys, you can use:

Or use OpenSSL from command line:

API Reference

SecureWebhookHelper

Constructor

Parameters:

• $encryptionKey - 32-byte encryption key
• $hmacKey - 32-byte HMAC key

Throws:

• InvalidArgumentException - If keys are not exactly 32 bytes

tryDecryptAndVerifyWithIvPrefix

Parameters:

• $guid - Webhook GUID
• $webhookType - Type of webhook
• $base64PayloadWithIv - Base64-encoded encrypted payload with IV prefix
• $signature - HMAC-SHA256 signature (hex string)
• $decryptedJson - Output parameter containing decrypted JSON on success

Returns:

• true if decryption and verification succeeded
• false if decryption failed or signature is invalid

Local Development (Laravel)

If you want to develop and test this package locally in your Laravel project before publishing to Packagist, you can load it directly via autoload.

1. Edit your Laravel project's composer.json and add to the autoload-dev section:

2. Reload the autoloader:

3. Now you can use the class in your Laravel application:

Any changes you make to the source files in /absolute/path/to/PHP_OlmedDataBus.Webhooks/src/ will be immediately available in your Laravel project.

Note: Remember to remove this entry from autoload-dev and install the package normally via Composer once it's published to Packagist.