suredonation_paypal_webhook_handle_event Filter Hook

Overview

The suredonation_paypal_webhook_handle_event filter allows developers to handle PayPal webhook events that are not processed natively by SureDonation.

SureDonation natively processes the following PayPal webhook events:

• PAYMENT.CAPTURE.COMPLETED
• PAYMENT.CAPTURE.DENIED
• PAYMENT.CAPTURE.REFUNDED

This filter runs for other event types, allowing developers to add custom handling for additional PayPal events. SureDonation Pro also uses this filter for events such as BILLING.SUBSCRIPTION.* and PAYMENT.SALE.*.

When to Use This Filter

Use this filter when you need to process a PayPal webhook event that is not handled by SureDonation by default.

For example, you can use it to:

• Handle subscription events.
• Process PayPal sale events.
• Record custom transaction information.
• Trigger custom workflows.
• Integrate PayPal events with another system.

Filter Signature

apply_filters( 'suredonation_paypal_webhook_handle_event', null, $event_type, $event_resource, $mode);

apply_filters( 'suredonation_paypal_webhook_handle_event', null, $event_type, $event_resource, $mode);

Parameters

Return Value

This filter uses a short-circuit contract. Your callback should return one of the following values:

Basic Usage

Use add_filter() to register your callback.

add_filter(  'suredonation_paypal_webhook_handle_event',  'your_custom_function', 10,  4);

function your_custom_function(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    // Return null if you do not handle this event.

    return $result;

}

add_filter(  'suredonation_paypal_webhook_handle_event',  'your_custom_function', 10,  4);

function your_custom_function(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    // Return null if you do not handle this event.

    return $result;

}

Example: Handle a PayPal Sale Event

The following example handles the PAYMENT.SALE.COMPLETED event.

add_filter(  'suredonation_paypal_webhook_handle_event',  'mysite_handle_sale', 10,   4);

function mysite_handle_sale(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    if ( 'PAYMENT.SALE.COMPLETED' === $event_type ) {

        mysite_record_sale( $event_resource );

        return true;

    }

    return $result;

}

add_filter(  'suredonation_paypal_webhook_handle_event',  'mysite_handle_sale', 10,   4);

function mysite_handle_sale(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    if ( 'PAYMENT.SALE.COMPLETED' === $event_type ) {

        mysite_record_sale( $event_resource );

        return true;

    }

    return $result;

}

How the Example Works

1. The callback receives the PayPal webhook event.
2. It checks whether the event type is PAYMENT.SALE.COMPLETED.
3. If the event matches, custom processing is performed.
4. The callback returns true to indicate successful handling.
5. Other event types return the original $result.

Example: Handle a Subscription Event

You can also use the filter to process PayPal subscription events.

add_filter(  'suredonation_paypal_webhook_handle_event',   'mysite_handle_subscription', 10,   4);

function mysite_handle_subscription(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    if ( 'BILLING.SUBSCRIPTION.CREATED' === $event_type ) {

        mysite_process_subscription( $event_resource );

        return true;

    }

    return $result;

}

add_filter(  'suredonation_paypal_webhook_handle_event',   'mysite_handle_subscription', 10,   4);

function mysite_handle_subscription(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    if ( 'BILLING.SUBSCRIPTION.CREATED' === $event_type ) {

        mysite_process_subscription( $event_resource );

        return true;

    }

    return $result;

}

Handling Errors

If your custom processing fails, return a WP_Error.

add_filter(  'suredonation_paypal_webhook_handle_event', 'mysite_handle_custom_event', 10,  4);

function mysite_handle_custom_event(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    if ( 'PAYMENT.SALE.COMPLETED' === $event_type ) {

        $success = mysite_record_sale( $event_resource );

        if ( ! $success ) {

            return new WP_Error(

                'custom_processing_failed',

                __( 'Unable to process the PayPal sale.', 'my-plugin' )

            );

        }

        return true;

    }

    return $result;

}

add_filter(  'suredonation_paypal_webhook_handle_event', 'mysite_handle_custom_event', 10,  4);

function mysite_handle_custom_event(

    $result,

    $event_type,

    $event_resource,

    $mode

) {

    if ( 'PAYMENT.SALE.COMPLETED' === $event_type ) {

        $success = mysite_record_sale( $event_resource );

        if ( ! $success ) {

            return new WP_Error(

                'custom_processing_failed',

                __( 'Unable to process the PayPal sale.', 'my-plugin' )

            );

        }

        return true;

    }

    return $result;

}

Webhook Processing Flow

The filter is part of the PayPal webhook processing flow:

1. PayPal sends a webhook event to SureDonation.
2. SureDonation identifies the PayPal event type.
3. Natively supported events are processed by SureDonation.
4. Other event types reach the default branch.
5. The suredonation_paypal_webhook_handle_event filter is applied.
6. Your callback can process the event.
7. Return true when processing succeeds.
8. Return null when the event is not handled.
9. Return a WP_Error when processing fails.

Important: Return the Original Result

If your callback does not handle the event, always return the original $result.

return $result;

The initial value is null. Returning it ensures that unrelated PayPal webhook events are not incorrectly marked as handled.

Related Hooks

• Suredonation_webhook_handle_event: Allows developers to handle additional Stripe webhook events.
• Suredonation_paypal_sdk_args: Allows developers to modify PayPal SDK configuration arguments.