<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Contract;

use apexl\Io\modules\payment\Dto\WebhookEvent;

/**
 * Gateway can receive + verify webhooks.
 *
 * Webhooks are how the gateway notifies us of state changes outside the
 * synchronous checkout flow: successful charges, failed payments,
 * subscription updates, refunds, disputes, etc. Each gateway has its own
 * signing format (Stripe HMAC, PayPal IPN-style, Revolut HMAC) — the
 * adapter handles verification + parses into a normalised event the
 * consumer can fan out.
 */
interface WebhookHandlerInterface
{
    /**
     * Verify the raw webhook payload's authenticity using the gateway's
     * signing scheme + returns a parsed event. Throws on invalid signature
     * / replay / malformed payload.
     *
     * @param string              $rawPayload          unmodified request body
     * @param array<string, string> $headers           normalised header dict
     */
    public function parseWebhook(string $rawPayload, array $headers): WebhookEvent;
}
