Handling Callbacks

Webhooks allow you to receive real-time notifications about your transactions. A webhook is fired whenever a transaction reaches a terminal status change: SUCCESS, FAILED, TIMEOUT, or REVERSED.

Payload Shape

The webhook POST body contains the following JSON structure:

{
  "status": "SUCCESS",
  "order_number": "COMP-20260703-A1B2C3D4",
  "vendor_reference": "TX-998877",
  "amount": "1500.00",
  "currency": "XAF",
  "completed_at": "2026-07-03T10:01:05+00:00",
  "provider_status": "SUCCESS",
  "failure_reason": null
}

Verifying Signatures

To ensure that the webhook genuinely originated from EasyTransact, each payload is signed.

The headers included with each webhook request are:

X-Signature (or X-Facilitator-Signature): The HMAC-SHA256 signature.
X-Timestamp: The Unix timestamp when the request was sent.

Validation Process

To verify the signature:

Extract the X-Signature and X-Timestamp headers from the incoming request.
Concatenate the raw JSON string payload and the timestamp: payload + timestamp.
Compute the HMAC-SHA256 signature using your Webhook Secret (or your active API Secret as a fallback).
Compare your computed signature with the X-Signature header.

Code Sample (Python)

import hmac
import hashlib

def verify_easytransact_webhook(payload_body_str, timestamp, signature, secret_key):
    """
    Verifies the webhook signature.
    
    :param payload_body_str: The raw JSON string from the request body
    :param timestamp: The 'X-Timestamp' header value
    :param signature: The 'X-Signature' header value
    :param secret_key: Your Webhook Secret or API Secret
    """
    # Concatenate the raw payload string and the timestamp
    signature_payload = f"{payload_body_str}{timestamp}"
    
    # Compute HMAC SHA256
    computed_signature = hmac.new(
        secret_key.encode('utf-8'),
        signature_payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Securely compare signatures
    return hmac.compare_digest(computed_signature, signature)

Handling Callbacks

Handling Callbacks

Payload Shape

Verifying Signatures

Validation Process

Code Sample (Python)

On this page