🕸️ Webhooks

HeedPay uses webhooks to notify your application asynchronously when events occur on your merchant profile context. When a payment transaction resolves successfully, an HTTP POST payload is delivered directly to your pre-configured endpoint listener directory.

Critical Integration Security Implementation

Because callback server targets are exposed to the public internet, you must rigorously validate incoming packet origins to eliminate structural risk vectors. Follow this sequence ruleset strictly upon incoming packet registration:

Verify Request Signature Matrix

Compute the internal authorization payload signature context and validate against the X-HeedPay-Signature transmission block values beforehand to establish explicit authenticity.

Mitigate Race-Conditions & Duplicate Requests

Log and check the unique transaction reference keys on your data persistence layer to safely enforce idempotency and avoid processing duplicate events.

Perform Explicit Server-Side Re-queries

Always execute an isolated outbound handshake request targeting our transaction fetch verification endpoint to confidently pull current truth matrix states before modifying critical system values.

Notification Payload Sample

Typical structural representation delivered to your target server route path on event fires.

EVENT TYPE: VIRTUAL_DEPOSIT
{ "eventType": "VIRTUAL_DEPOSIT", "status": "success", "sign": "fgggertg5teerttergertt4r2335413423r4t523414235343r334r3434235rwefr34", "message": "Your payment has been successfully processed.", "timestamp": "2024-11-22T13:00:04.256092Z", "bussinessId": "GR45G7HU89K", "data": { "amount_received": "100.00", "fee_deducted": "0.5", "amount_credited": "99.5", "session_id": "988625325234443568021345231247", "reference": "2034943894287423RESERVED" }, "sender": { "senderName": "Heedtech Universal", "senderAccountNumber": "6679854996", "senderBankName": "HeedPay Bank", "senderBankCode": "103212" }, "customer": { "name": "Heedtech Sahee(Heedpay)", "email": "john@gmail.com", "account": "5357321222", "customer_id": "23456788445678RESERVED" } }

Signature Verification Example

Sample validation script implementation for native PHP runtime setups.

VERIFY.PHP
<?php // 1. Get the raw input data sent from HeedPay $payload = file_get_contents('php://input'); // 2. Retrieve the signature sent from the HTTP Request Headers $headers = getallheaders(); $heedpay_signature = isset($headers['X-HeedPay-Signature']) ? $headers['X-HeedPay-Signature'] : ''; // 3. Your secret API key stored securely on your server $apiKey = "YOUR_HEEDPAY_API_KEY"; // 4. Calculate your local signature check $expected_signature = hash_hmac('sha256', $payload, $apiKey); // 5. Match verification status cleanly if (hash_equals($expected_signature, $heedpay_signature)) { // Webhook is authentic! Process credit safely. http_response_code(200); echo "success"; } else { // Fraud alert! Reject connection immediately http_response_code(401); echo "Unauthorized Signature Mismatch"; } ?>

Documentation last updated 1 year ago

Documentation Navigation

Welcome to HeedPay Authentication Instructions Create Virtual Account Create Dynamic Virtual Account Transfer