Configure webhook endpoints to receive real-time payment status updates with security validation and retry logic.

Set up your webhook endpoint, understand the payload structure, and implement security validation for authentic callbacks.

Webhook Setup

  1. Endpoint Requirements

    Your webhook endpoint must meet specific requirements for reliable delivery and security.

    Requirements:
    • HTTPS endpoint (required for production)
    • Return HTTP 200 for successful processing
    • Handle POST requests with JSON payload
    • Respond within 30 seconds
    • Accessible from our servers

  2. Webhook URL Validation

    We validate webhook URLs during payment initiation to ensure they're accessible and properly configured.

    Validation Process:
    1. URL format validation
    2. HTTPS requirement check
    3. Accessibility test (GET request)
    4. Response time validation
    5. Server error check (< 500 status)

  3. Retry Behavior

    Failed webhooks are automatically retried with exponential backoff to ensure delivery.

    Retry Schedule:
    Attempt 1: Immediate
    Attempt 2: +1 minute
    Attempt 3: +5 minutes
    Attempt 4: +15 minutes
    Attempt 5: +30 minutes
    Final: +1 hour
  4. Payload Structure

Webhook Payload

  1. Complete Payload Structure

    JSON payload structure sent to your webhook URL with all transaction details.

    { "request_id": "REQ_abc123def456", "status": "completed", "amount": 100, "msisdn": "254712345678", "transaction_id": "NLJ7RT61SV", "mpesa_receipt_number": "NLJ7RT61SV", "result_code": "0", "result_desc": "The service request is processed successfully.", "timestamp": "2025-01-27T10:30:00Z", "checkout_request_id": "ws_CO_27072023123456789", "merchant_request_id": "29115-34620561-1", "callback_metadata": { "Amount": 100.0, "MpesaReceiptNumber": "NLJ7RT61SV", "TransactionDate": 20250127185641, "PhoneNumber": 254712345678, "Balance": 0.0 }, "raw_callback": { "Body": { "stkCallback": { "MerchantRequestID": "29115-34620561-1", "CheckoutRequestID": "ws_CO_27072023123456789", "ResultCode": 0, "ResultDesc": "The service request is processed successfully." } } }, "metadata": { "business_name": "Your Business Name", "shortcode": "880100", "account_number": "ACC001", "api_secret": "sc_a1b2c3d4e5f6g7h8i9j0k1l2m3n4", "webhook_attempt": 1, "max_attempts": 5, "processed_at": "2025-01-27T10:30:00Z" } }

  2. Webhook Headers

    Security headers included with webhook requests for validation and authentication.

    Headers:
    X-API-Key: your_api_key
    X-Link-ID: shortcode_tracking_code
    X-Signature: hmac_sha256_signature
    X-Request-ID: request_identifier
    X-Timestamp: iso_timestamp
    Content-Type: application/json
    User-Agent: M-Pesa-API/1.0
  3. Security Validation

Security Validation

  1. HMAC Signature Verification

    Verify webhook authenticity using HMAC SHA256 signature validation.

    PHP 
    {"error":"Invalid signature"}

  2. Header Validation

    Validate API key and tracking code in webhook headers to ensure authenticity.

    Validation Steps:
    1. Check X-API-Key matches your API key
    2. Verify X-Link-ID matches expected tracking code
    3. Validate X-Signature using HMAC SHA256
    4. Check X-Timestamp for replay attacks
    5. Process webhook if all checks pass

  3. Webhook Response

    Your webhook endpoint must return appropriate HTTP status codes for proper delivery tracking.

    Response Requirements:
    • Return HTTP 200 for successful processing
    • Return HTTP 401 for authentication failures
    • Return HTTP 500 for processing errors
    • Include JSON response body (optional)
    • Respond within 30 seconds
  4. Error Codes

Status Types

  1. Payment Statuses

    Different payment statuses you'll receive in webhook callbacks.

    Status Values:
    • completed - Payment successful
    • failed - Payment failed
    • cancelled - User cancelled
    • timeout - User didn't respond
    • insufficient_funds - Not enough balance
    • invalid_pin - Wrong PIN entered

  2. Result Codes

    M-Pesa result codes provide detailed information about transaction outcomes.

    Common Result Codes:
    • 0 - Success
    • 1 - Insufficient funds
    • 1032 - User cancelled
    • 1037 - Timeout
    • 2001 - Invalid PIN
    • 1025 - System error
  3. Best Practices