Verifying Payment Provider Webhooks in PHP

Payment webhooks require provider-specific signature formats, exact raw payloads and deduplication.

What It Does

Payment webhooks require provider-specific signature formats, exact raw payloads and deduplication. The following examples distinguish a normal use case, a boundary case and a practical application.

Requirements and Compatibility

A provider signing secret or verification key, the unmodified HTTP request body and durable event deduplication.

The code focuses on the core concept. Production implementation may also need routes, validation, persistence, authorization or deployment tooling.

Example 1: Basic Behavior

Understand the primary operation and its inputs.

<?php
$body = '{"event":"paid","id":"e7"}';
$secret = 'test-only-secret';
$header = hash_hmac('sha256', $body, $secret);
var_dump(hash_equals(hash_hmac('sha256', $body, $secret), $header));

Example 2: Another Case

Check failure behavior or a different execution path.

<?php
$age = abs(time() - (time() - 20));
var_dump($age <= 300); // Reject messages outside the timestamp window

Practical Example: Putting It to Use

Validate the payment event type and order amount after signature verification.

<?php
$event = ['id' => 'evt-4', 'type' => 'payment.succeeded', 'amount' => 1099, 'currency' => 'USD'];
if ($event['type'] === 'payment.succeeded' && $event['amount'] > 0) echo $event['id'];
// First verify the provider signature and then reconcile the payment with your database.

Important Behavior and Edge Cases

Do not trust a browser redirect as evidence of payment; reconcile amounts and IDs against provider data.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• Payment webhooks require provider-specific signature formats, exact raw payloads and deduplication.
• Do not trust a browser redirect as evidence of payment; reconcile amounts and IDs against provider data.
• Verify signatures and make transaction updates idempotent in the database.

Before adapting these examples, verify the return values, test the failure paths and confirm that your application meets its security and environment requirements.