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

`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

pay-user.completed Pay user credited

pay-user.failed Pay user 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 Fees

Next Models