Event Service

Overview

The Event Service processes inbound webhook notifications from payment processors using the PHP SDK. Instead of polling for status updates, webhooks deliver real-time notifications when payment states change.

Business Use Cases:

• Payment completion - Receive instant notification when payments succeed

• Failed payment handling - Get notified of declines for retry logic

• Refund tracking - Update systems when refunds complete

• Dispute alerts - Immediate notification of new chargebacks

Operations

Operation	Description	Use When
handleEvent	Process webhook from payment processor. Verifies and parses incoming connector notifications.	Receiving webhook POST from Stripe, Adyen, etc.

SDK Setup

use HyperswitchPrism\EventClient;

$eventClient = new EventClient([
    'connector' => 'stripe',
    'apiKey' => 'YOUR_API_KEY',
    'environment' => 'SANDBOX'
]);

Common Patterns

Webhook Processing Flow

Flow Explanation:

1. Provider sends - When a payment updates, the provider sends a webhook to your endpoint.

2. Verify and parse - Pass the raw payload to handleEvent for verification and transformation.

3. Process event - Receive a structured event object with unified format.

4. Update systems - Update your database, fulfill orders, or trigger notifications.

Webhook Security Example

<?php
// webhook-handler.php
use HyperswitchPrism\EventClient;

$eventClient = new EventClient([
    'connector' => 'stripe',
    'apiKey' => 'YOUR_API_KEY'
]);

$payload = file_get_contents('php://input');
$headers = getallheaders();

try {
    $event = $eventClient->handleEvent([
        'payload' => $payload,
        'headers' => $headers,
        'webhookSecret' => 'whsec_xxx'
    ]);

    if ($event['type'] === 'payment.captured') {
        // Fulfill order
        fulfillOrder($event['data']['merchantTransactionId']);
    }

    http_response_code(200);
    echo 'OK';
} catch (Exception $e) {
    http_response_code(400);
    echo 'Error: ' . $e->getMessage();
}

Next Steps

• Payment Service - Handle payment webhooks

• Refund Service - Process refund notifications

• Dispute Service - Handle dispute alerts