How to securely integrate Stripe Payment webhook endpoints into WordPress custom plugins using WordPress Database Class ($wpdb)
Securing Stripe Webhook Endpoints in WordPress
Integrating Stripe webhooks into a custom WordPress plugin requires a robust approach to security and data integrity. This guide details how to implement a secure webhook endpoint, validate incoming requests, and persist relevant payment data using WordPress’s built-in database class, $wpdb.
1. Setting Up the Webhook Endpoint
Your custom plugin needs a dedicated endpoint to receive Stripe webhook events. This is typically a publicly accessible URL. We’ll use WordPress’s AJAX API for this, which provides a structured way to handle requests and ensures proper WordPress environment loading.
First, register an AJAX action in your plugin’s main file or an included setup file. This action will be hooked into wp_ajax_your_stripe_webhook_action for logged-in users and wp_ajax_nopriv_your_stripe_webhook_action for non-logged-in users. Since webhooks are typically unauthenticated requests from Stripe, we’ll focus on the nopriv hook.
Plugin Setup (Example: my-stripe-plugin.php)
<?php
/*
Plugin Name: My Secure Stripe Integration
Description: Handles Stripe webhook events securely.
Version: 1.0
Author: Antigravity
*/
// Prevent direct access
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
// Define webhook action hook
define( 'MY_STRIPE_WEBHOOK_ACTION', 'my_stripe_webhook_handler' );
// Enqueue script to pass AJAX URL (optional, but good practice for JS interaction)
function my_stripe_enqueue_scripts() {
wp_enqueue_script( 'my-stripe-script', plugin_dir_url( __FILE__ ) . 'js/my-stripe-script.js', array( 'jquery' ), '1.0', true );
wp_localize_script( 'my-stripe-script', 'myStripeAjax', array(
'ajax_url' => admin_url( 'admin-ajax.php' ),
'action' => MY_STRIPE_WEBHOOK_ACTION,
'nonce' => wp_create_nonce( MY_STRIPE_WEBHOOK_ACTION . '_nonce' ), // For potential JS-initiated AJAX calls
) );
}
add_action( 'wp_enqueue_scripts', 'my_stripe_enqueue_scripts' );
// Register the AJAX webhook handler for non-logged-in users
add_action( 'wp_ajax_nopriv_' . MY_STRIPE_WEBHOOK_ACTION, 'my_stripe_handle_webhook' );
/**
* Handles incoming Stripe webhook requests.
*/
function my_stripe_handle_webhook() {
// Security checks and processing will go here
// This function will be called via AJAX
// For direct webhook access, we'll bypass AJAX structure slightly for clarity in the next step.
// For direct webhook access, we'll use a rewrite rule or a dedicated file.
// However, for simplicity and leveraging WordPress, we'll simulate direct access
// by ensuring this function is called with the correct POST data.
// In a real-world scenario, you might create a dedicated file like `wp-content/plugins/my-stripe-plugin/webhook.php`
// and configure Stripe to point to `yourdomain.com/wp-content/plugins/my-stripe-plugin/webhook.php`.
// For this example, we'll assume the AJAX handler is sufficient for demonstration.
// The actual processing logic is in `my_stripe_process_webhook_event()`.
my_stripe_process_webhook_event();
// Respond to Stripe
wp_send_json_success( array( 'message' => 'Webhook received and processed.' ), 200 );
wp_die(); // This is crucial for AJAX handlers
}
/**
* Core webhook event processing logic.
*/
function my_stripe_process_webhook_event() {
// This function will contain the main logic: signature verification, data parsing, DB operations.
// We'll implement this in the next sections.
error_log( 'my_stripe_process_webhook_event called.' );
}
// Include other necessary files
require_once plugin_dir_path( __FILE__ ) . 'includes/class-my-stripe-webhook-handler.php';
require_once plugin_dir_path( __FILE__ ) . 'includes/db-operations.php';
?>
While the AJAX approach is useful for JavaScript-driven interactions, Stripe webhooks are typically sent via direct HTTP POST requests. For a production environment, it’s often cleaner to create a dedicated file (e.g., wp-content/plugins/my-stripe-plugin/webhook.php) and configure Stripe to point to a URL like https://yourdomain.com/wp-content/plugins/my-stripe-plugin/webhook.php. This bypasses the WordPress AJAX overhead for the initial request, though you’ll still need to bootstrap WordPress to use $wpdb and other WordPress functions.
2. Verifying the Stripe Signature
Stripe signs its webhook requests using a signature to ensure they originate from Stripe and haven’t been tampered with. This is a critical security step. You’ll need your Stripe webhook signing secret, which can be found in your Stripe dashboard under Developers -> Webhooks.
The signature is sent in the Stripe-Signature HTTP header. The payload is sent as raw POST data. We’ll implement this verification within a dedicated class for better organization.
Webhook Handler Class (includes/class-my-stripe-webhook-handler.php)
<?php
// Prevent direct access
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
class My_Stripe_Webhook_Handler {
private $webhook_secret;
private $stripe_client; // Assuming you have a Stripe PHP client instance
public function __construct( $webhook_secret ) {
$this->webhook_secret = $webhook_secret;
// Initialize Stripe client if needed for other operations
// require_once 'vendor/autoload.php'; // If using Composer
// \Stripe\Stripe::setApiKey( 'YOUR_STRIPE_SECRET_KEY' );
// $this->stripe_client = new \Stripe\StripeClient( 'YOUR_STRIPE_SECRET_KEY' );
}
/**
* Verifies the Stripe signature of the incoming request.
*
* @return bool True if the signature is valid, false otherwise.
*/
public function verify_signature() {
if ( empty( $_SERVER['HTTP_STRIPE_SIGNATURE'] ) ) {
error_log( 'Stripe Signature header is missing.' );
return false;
}
$signature = $_SERVER['HTTP_STRIPE_SIGNATURE'];
$payload = file_get_contents( 'php://input' ); // Get raw POST data
if ( ! $payload ) {
error_log( 'Stripe webhook payload is empty.' );
return false;
}
// Use Stripe's PHP library to verify the signature
// Ensure you have the Stripe PHP SDK installed (e.g., via Composer)
// If not using Composer, you'd need to include the Stripe library manually.
try {
\Stripe\Webhook::constructEvent(
$payload, $signature, $this->webhook_secret
);
return true;
} catch ( \UnexpectedValueException $e ) {
// Invalid payload
error_log( 'Stripe webhook signature verification failed: Invalid payload. ' . $e->getMessage() );
return false;
} catch ( \Stripe\Exception\SignatureVerificationException $e ) {
// Invalid signature
error_log( 'Stripe webhook signature verification failed: Invalid signature. ' . $e->getMessage() );
return false;
} catch ( Exception $e ) {
// Other errors
error_log( 'Stripe webhook signature verification encountered an unexpected error: ' . $e->getMessage() );
return false;
}
}
/**
* Parses the webhook event payload.
*
* @return array|null The parsed event data or null on failure.
*/
public function parse_payload() {
$payload = file_get_contents( 'php://input' );
if ( ! $payload ) {
return null;
}
// Stripe events are JSON
$event_data = json_decode( $payload, true );
return $event_data;
}
}
?>
To use this class, you’d instantiate it within your webhook processing function. The webhook secret should be stored securely, ideally in your wp-config.php file or a custom options table, not directly in the plugin code.
Storing the Webhook Secret
// In your main plugin file (my-stripe-plugin.php) or a configuration file:
// Retrieve from wp-config.php (recommended)
if ( ! defined( 'MY_STRIPE_WEBHOOK_SECRET' ) ) {
// Fallback or error handling if not defined
// For production, ensure this is always defined in wp-config.php
define( 'MY_STRIPE_WEBHOOK_SECRET', '' );
}
// Instantiate the handler
$webhook_handler = new My_Stripe_Webhook_Handler( MY_STRIPE_WEBHOOK_SECRET );
// In your my_stripe_handle_webhook() function:
function my_stripe_handle_webhook() {
// ... (AJAX setup if used)
$webhook_handler = new My_Stripe_Webhook_Handler( MY_STRIPE_WEBHOOK_SECRET );
if ( ! $webhook_handler->verify_signature() ) {
wp_send_json_error( array( 'message' => 'Invalid signature.' ), 400 );
wp_die();
}
$event_data = $webhook_handler->parse_payload();
if ( ! $event_data ) {
wp_send_json_error( array( 'message' => 'Invalid payload.' ), 400 );
wp_die();
}
// Process the event
my_stripe_process_webhook_event( $event_data );
wp_send_json_success( array( 'message' => 'Webhook received and processed.' ), 200 );
wp_die();
}
// Modify the core processing function to accept event data
function my_stripe_process_webhook_event( $event_data ) {
// ... processing logic ...
error_log( 'Processing Stripe event: ' . $event_data['type'] );
}
3. Processing the Event and Database Operations
Once the signature is verified, you need to parse the event data and perform actions based on the event type (e.g., payment_intent.succeeded, charge.refunded). We’ll use $wpdb to store relevant transaction details in a custom database table.
3.1. Creating a Custom Database Table
It’s best practice to create a custom table for your plugin’s data rather than cluttering the wp_options table or using post meta for structured transaction data. This table should store essential information like the Stripe event ID, object ID (e.g., Payment Intent ID), customer ID, amount, currency, status, and timestamp.
You can create this table during plugin activation. Ensure you include a version number for future schema updates.
// In your main plugin file (my-stripe-plugin.php) or a dedicated setup file:
/**
* Plugin activation hook.
*/
function my_stripe_plugin_activate() {
global $wpdb;
$table_name = $wpdb->prefix . 'my_stripe_transactions';
$charset_collate = $wpdb->get_charset_collate();
$sql = "CREATE TABLE $table_name (
id mediumint(9) NOT NULL AUTO_INCREMENT,
stripe_event_id varchar(255) NOT NULL UNIQUE,
stripe_object_id varchar(255) NOT NULL, -- e.g., PaymentIntent ID, Charge ID
stripe_object_type varchar(50) NOT NULL, -- e.g., 'payment_intent', 'charge'
customer_id varchar(255) NULL,
amount bigint(20) NOT NULL, -- Amount in cents
currency varchar(10) NOT NULL,
status varchar(50) NOT NULL,
event_type varchar(100) NOT NULL,
created_at datetime DEFAULT CURRENT_TIMESTAMP NOT NULL,
updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP NOT NULL,
PRIMARY KEY (id),
KEY idx_stripe_object_id (stripe_object_id),
KEY idx_customer_id (customer_id)
) $charset_collate;";
require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
dbDelta( $sql );
// Store plugin version
add_option( 'my_stripe_plugin_version', '1.0' );
}
register_activation_hook( __FILE__, 'my_stripe_plugin_activate' );
/**
* Plugin deactivation hook (optional cleanup).
*/
function my_stripe_plugin_deactivate() {
// Optional: clean up options, etc.
}
register_deactivation_hook( __FILE__, 'my_stripe_plugin_deactivate' );
// Add this to your main plugin file
// Ensure MY_STRIPE_WEBHOOK_SECRET is defined before this point
// require_once plugin_dir_path( __FILE__ ) . 'includes/class-my-stripe-webhook-handler.php';
// require_once plugin_dir_path( __FILE__ ) . 'includes/db-operations.php'; // This will contain the DB logic
3.2. Database Operations Class/Functions
Create a file (e.g., includes/db-operations.php) to handle database interactions. This keeps your webhook handler cleaner.
<?php
// Prevent direct access
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Inserts or updates transaction data in the custom table.
*
* @param array $data Transaction data.
* @return int|false The row ID on success, false on failure.
*/
function my_stripe_save_transaction_data( $data ) {
global $wpdb;
$table_name = $wpdb->prefix . 'my_stripe_transactions';
// Basic validation
$required_keys = array( 'stripe_event_id', 'stripe_object_id', 'stripe_object_type', 'amount', 'currency', 'status', 'event_type' );
foreach ( $required_keys as $key ) {
if ( ! isset( $data[ $key ] ) ) {
error_log( "Missing required key for saving transaction: {$key}" );
return false;
}
}
$insert_data = array(
'stripe_event_id' => sanitize_text_field( $data['stripe_event_id'] ),
'stripe_object_id' => sanitize_text_field( $data['stripe_object_id'] ),
'stripe_object_type' => sanitize_text_field( $data['stripe_object_type'] ),
'customer_id' => isset( $data['customer_id'] ) ? sanitize_text_field( $data['customer_id'] ) : null,
'amount' => intval( $data['amount'] ),
'currency' => sanitize_text_field( $data['currency'] ),
'status' => sanitize_text_field( $data['status'] ),
'event_type' => sanitize_text_field( $data['event_type'] ),
);
$format = array(
'%s', // stripe_event_id
'%s', // stripe_object_id
'%s', // stripe_object_type
'%s', // customer_id (can be null)
'%d', // amount
'%s', // currency
'%s', // status
'%s', // event_type
);
// Check if the event already exists to prevent duplicates
$existing_event = $wpdb->get_row( $wpdb->prepare( "SELECT id FROM $table_name WHERE stripe_event_id = %s", $insert_data['stripe_event_id'] ) );
if ( $existing_event ) {
// Optionally update existing record if status or other fields changed
// For simplicity, we'll just log that it already exists.
error_log( "Stripe event {$insert_data['stripe_event_id']} already processed." );
return $existing_event->id; // Return existing ID
} else {
// Insert new record
$result = $wpdb->insert( $table_name, $insert_data, $format );
if ( $result === false ) {
error_log( "Failed to insert transaction data into {$table_name}. Error: " . $wpdb->last_error );
return false;
}
return $wpdb->insert_id;
}
}
/**
* Retrieves transaction data by Stripe object ID.
*
* @param string $stripe_object_id The Stripe object ID (e.g., PaymentIntent ID).
* @return object|null The transaction data object or null if not found.
*/
function my_stripe_get_transaction_by_object_id( $stripe_object_id ) {
global $wpdb;
$table_name = $wpdb->prefix . 'my_stripe_transactions';
$transaction = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table_name WHERE stripe_object_id = %s ORDER BY created_at DESC LIMIT 1", $stripe_object_id ) );
return $transaction;
}
// Add more functions as needed, e.g., for refunds, subscriptions, etc.
?>
3.3. Integrating DB Operations into the Handler
Now, modify the my_stripe_process_webhook_event function to use these database operations.
// In your main plugin file (my-stripe-plugin.php)
/**
* Core webhook event processing logic.
*
* @param array $event_data The parsed Stripe event data.
*/
function my_stripe_process_webhook_event( $event_data ) {
if ( ! $event_data || ! isset( $event_data['type'] ) ) {
error_log( 'Invalid event data received in my_stripe_process_webhook_event.' );
return;
}
$event_type = $event_data['type'];
$event_object = $event_data['data']['object']; // The actual Stripe object (e.g., PaymentIntent)
// Ensure we have the necessary data
if ( ! isset( $event_object['id'], $event_object['amount'], $event_object['currency'] ) ) {
error_log( "Incomplete object data for event type: {$event_type}" );
return;
}
$transaction_data = array(
'stripe_event_id' => $event_data['id'],
'stripe_object_id' => $event_object['id'],
'stripe_object_type' => $event_object['object'], // e.g., 'payment_intent', 'charge'
'customer_id' => isset( $event_object['customer'] ) ? $event_object['customer'] : null,
'amount' => $event_object['amount'],
'currency' => $event_object['currency'],
'status' => $event_object['status'], // Status depends on the object type
'event_type' => $event_type,
);
// Handle specific event types
switch ( $event_type ) {
case 'payment_intent.succeeded':
// Payment succeeded, record it.
// You might want to check if it's a new payment or a confirmation.
// If using Stripe Checkout, you'd typically handle 'checkout.session.completed'.
my_stripe_save_transaction_data( $transaction_data );
// Trigger order fulfillment, send confirmation emails, etc.
error_log( "PaymentIntent {$event_object['id']} succeeded." );
break;
case 'payment_intent.payment_failed':
// Payment failed, record it.
my_stripe_save_transaction_data( $transaction_data );
error_log( "PaymentIntent {$event_object['id']} failed." );
// Notify customer, retry logic, etc.
break;
case 'charge.refunded':
// A charge was refunded. Update our records.
$original_charge_id = $event_object['charge'] ?? null; // Stripe might provide the charge ID directly
if ( $original_charge_id ) {
// Find the transaction related to this charge
$existing_transaction = my_stripe_get_transaction_by_object_id( $original_charge_id );
if ( $existing_transaction ) {
// Update the status or add refund details
global $wpdb;
$table_name = $wpdb->prefix . 'my_stripe_transactions';
$wpdb->update(
$table_name,
array(
'status' => 'refunded', // Or a more specific status
// Add refund amount if available in the event object
),
array( 'id' => $existing_transaction->id ),
array( '%s' ), // Format for status
array( '%d' ) // Format for id
);
error_log( "Charge {$original_charge_id} was refunded. Transaction ID: {$existing_transaction->id}" );
} else {
error_log( "Could not find original transaction for refund of charge {$original_charge_id}." );
// Optionally, save the refund as a new event if it's a standalone refund.
// Ensure transaction_data reflects refund details if available.
my_stripe_save_transaction_data( array_merge( $transaction_data, array( 'status' => 'refunded', 'event_type' => $event_type ) ) );
}
} else {
error_log( "Refund event received without a charge ID." );
}
break;
// Add cases for other relevant events like:
// 'checkout.session.completed'
// 'customer.subscription.created', 'customer.subscription.updated', 'customer.subscription.deleted'
// 'invoice.payment_succeeded', 'invoice.payment_failed'
default:
// Handle other event types or ignore them
error_log( "Unhandled Stripe event type: {$event_type}" );
break;
}
}
4. Handling Stripe Checkout Session Completion
If you’re using Stripe Checkout, the primary event you’ll likely want to handle is checkout.session.completed. This event signifies that a customer has successfully completed the checkout flow. The event object contains details about the session, including the customer, line items, and importantly, the payment_status.
// Add this case to the switch statement in my_stripe_process_webhook_event()
case 'checkout.session.completed':
$session = $event_object; // The event object is the session itself
// Check payment status
if ( $session['payment_status'] === 'paid' ) {
// Payment is successful.
// The 'customer' and 'metadata' fields are crucial here.
$customer_id = $session['customer'] ?? null;
$payment_intent_id = $session['payment_intent'] ?? null; // This is the PaymentIntent ID
// Retrieve metadata if you passed any during session creation
// Example: $metadata = $session['metadata'];
// $order_id = $metadata['order_id'] ?? null;
if ( $payment_intent_id ) {
// Fetch the PaymentIntent to get final details if needed
// (Requires Stripe client initialized with secret key)
// try {
// $payment_intent = \Stripe\PaymentIntent::retrieve($payment_intent_id);
// $amount = $payment_intent->amount;
// $currency = $payment_intent->currency;
// $status = $payment_intent->status; // Should be 'succeeded'
// } catch ( Exception $e ) {
// error_log( "Failed to retrieve PaymentIntent {$payment_intent_id}: " . $e->getMessage() );
// // Handle error
// }
// Prepare data for our transaction table
$transaction_data = array(
'stripe_event_id' => $event_data['id'],
'stripe_object_id' => $payment_intent_id, // Use PaymentIntent ID as primary object ID
'stripe_object_type' => 'payment_intent', // Or 'checkout.session' if preferred
'customer_id' => $customer_id,
'amount' => $session['amount_total'], // Total amount including tax, shipping etc.
'currency' => $session['currency'],
'status' => $session['payment_status'], // 'paid'
'event_type' => $event_type,
);
// Save the transaction
$saved_id = my_stripe_save_transaction_data( $transaction_data );
if ( $saved_id ) {
error_log( "Checkout session {$session['id']} completed successfully. PaymentIntent: {$payment_intent_id} saved." );
// Trigger order fulfillment, send emails, update order status in WooCommerce/custom system.
// If you passed an order_id in metadata, use it here.
// Example: update_post_meta( $order_id, '_stripe_payment_status', 'paid' );
} else {
error_log( "Failed to save transaction data for completed checkout session {$session['id']}." );
}
} else {
error_log( "Checkout session {$session['id']} completed but no payment_intent found." );
// This might happen for 'no_payment_required' sessions. Handle accordingly.
}
} elseif ( $session['payment_status'] === 'unpaid' ) {
// Payment is not yet complete (e.g., requires further action or failed).
error_log( "Checkout session {$session['id']} completed but payment is unpaid." );
// Handle accordingly, perhaps update order status to 'pending payment'.
}
break;
5. Idempotency and Error Handling
Idempotency: Stripe may occasionally send the same webhook event more than once. Your webhook handler must be *idempotent*, meaning processing the same event multiple times should have the same effect as processing it once. The check for an existing stripe_event_id in my_stripe_save_transaction_data is a key part of achieving idempotency. If an event has already been processed, simply acknowledge it and do nothing further.
Error Handling: Implement comprehensive error logging using error_log(). Monitor your server logs for any issues. If Stripe receives a non-2xx response from your webhook endpoint, it will retry sending the event for a period. Ensure your endpoint returns a 200 OK status code as quickly as possible after receiving the request, even if processing takes longer. The actual processing logic should be decoupled or handled asynchronously if it’s time-consuming.
Stripe CLI for Testing: Use the Stripe CLI (stripe listen --forward-to localhost:8000/wp-json/my-stripe/v1/webhook or similar) to forward events to your local development environment. This is invaluable for testing your webhook logic without deploying to a live server.
6. Security Best Practices Summary
- Verify Signatures: Always verify the
Stripe-Signatureheader. - Use HTTPS: Ensure your WordPress site uses HTTPS.
- Secure Webhook Secret: Store your webhook signing secret securely (e.g., in
wp-config.php) and never commit it to version control. - Idempotency: Design your handlers to safely process duplicate events.
- Least Privilege: Grant your database user only the necessary permissions.
- Input Sanitization: Sanitize all data before inserting it into the database.
- Error Logging: Implement thorough logging to catch and diagnose issues.
- Rate Limiting: Consider implementing rate limiting on your webhook endpoint if you anticipate high traffic or potential abuse, although Stripe’s own security measures are robust.
- Event Filtering: Only process event types that your application needs.
By following these steps, you can build a secure, reliable, and robust Stripe webhook integration within your custom WordPress plugin, leveraging the power of $wpdb for persistent data storage.