Webhooks

Receive real-time notifications when events occur. Always verify webhook signatures before processing.

Setting Up Webhooks

Configure your webhook URL in the partner dashboard. HooPay will send POST requests to your endpoint when events occur.

Webhook Headers

Header	Description
`X-Webhook-Signature`	HMAC-SHA256 signature of the payload
`X-Webhook-Timestamp`	Unix timestamp when webhook was sent
`Content-Type`	application/json

Verifying Signatures

Always verify webhook signatures to ensure requests are from HooPay:

PHP

function verifyWebhook($payload, $signature, $timestamp, $secret) {
    // Check timestamp (5 minute tolerance)
    if (abs(time() - (int)$timestamp) > 300) {
        return false;
    }
    
    // Create signed payload
    $signedPayload = $timestamp . '.' . $payload;
    
    // Compute expected signature
    $expected = hash_hmac('sha256', $signedPayload, $secret);
    
    // Constant-time comparison
    return hash_equals($signature, $expected);
}

Open Webhook Tester

Webhook Events

Pay User Events

deposit.completed Deposit credited to user wallet

deposit.pending_funding Deposit queued - merchant insufficient funds

deposit.completed_after_funding Queued deposit completed after merchant top-up

deposit.failed Deposit failed

Collection Events

collection.completed Collection processed

collection.failed Collection failed

Refund Events

refund.completed Refund processed successfully

refund.failed Refund could not be processed

Example Payload

pay-user.completed

{
  "event": "pay-user.completed",
  "webhook_id": "whk_abc123xyz",
  "timestamp": 1701097800,
  "data": {
    "session_id": "pss_abc123xyz789",
    "partner_reference": "ORDER-12345",
    "amount": 99.99,
    "fee_amount": 2.50,
    "net_amount": 97.49,
    "currency": "USD",
    "status": "completed",
    "transaction_reference": "TXN-20251127-ABC",
    "completed_at": "2025-11-27T10:30:00Z",
    "metadata": {
      "order_type": "subscription"
    }
  }
}

Best Practices

Always verify signatures before processing
Respond with 2xx status within 5 seconds
Process webhooks asynchronously (use queues)
Store webhook_id to handle duplicates

Previous Transaction History

Next Models