handle Method

Overview

The handle method processes raw webhook payloads from payment processors. It verifies webhook signatures, parses the event data, and returns a normalized response with the event type and associated payment details.

Business Use Case: When Stripe sends a webhook notification that a payment succeeded, you need to verify it's authentic and update your order status. This method handles verification and parsing.

Purpose

Challenge	Solution
Signature verification	Automatically verifies webhook authenticity
Multiple formats	Normalizes Stripe, Adyen into consistent format
Security	Validates secrets before processing

Request Fields

Field	Type	Required	Description
merchantEventId	string	Yes	Your unique event reference
payload	string/object	Yes	Raw webhook body
headers	object	Yes	HTTP headers including signature
webhookSecret	string	Yes	Webhook signing secret

Response Fields

Field	Type	Description
eventType	string	Type: payment.captured, refund.succeeded, etc.
eventResponse	object	Payment/refund/dispute details
sourceVerified	boolean	Whether signature was verified
eventStatus	string	COMPLETE, INCOMPLETE

Example

SDK Setup

const { EventClient } = require('hyperswitch-prism');

const eventClient = new EventClient({
    connector: 'stripe',
    apiKey: 'YOUR_API_KEY'
});

Express.js Webhook Handler

app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
    const request = {
        merchantEventId: `evt_${Date.now()}`,
        payload: req.body,
        headers: req.headers,
        webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
    };

    try {
        const response = await eventClient.handle(request);

        if (response.eventType === 'payment.captured') {
            await fulfillOrder(response.eventResponse.paymentsResponse.merchantTransactionId);
        } else if (response.eventType === 'refund.succeeded') {
            await updateRefundStatus(response.eventResponse.refundsResponse);
        }

        res.json({ received: true });
    } catch (error) {
        res.status(400).json({ error: error.message });
    }
});

Response

{
    eventType: "payment.captured",
    eventResponse: {
        paymentsResponse: {
            merchantTransactionId: "txn_order_001",
            connectorTransactionId: "pi_3Oxxx...",
            status: "CAPTURED"
        }
    },
    sourceVerified: true,
    eventStatus: "COMPLETE"
}

Event Types

Event Type	Description
payment.authorized	Payment authorized, funds held
payment.captured	Payment completed
payment.failed	Payment declined
refund.succeeded	Refund processed
dispute.created	New chargeback received

Next Steps

• Payment Service - Process payment events
• Refund Service - Process refund events
• Dispute Service - Process dispute events