Webhook Validation

If you wish to integrate paypal webhooks in your website, one part of the setup is to receive webhooks. Creating webhook is not covered here, and could be followed from instruction here.

NOTE

PHP SDK WON'T work with webhook simulator, as it is using alternative method to retreive data.

PHP Currently does not support certificate chain validation, that is necessary to validate webhook directly, from received data. To resolve that, we need to use alternative, which includes making a GET call to obtain the data directly from PayPal.

Steps

1. Create atleast one webhook by either following a sample here, or go into developer docs. This needs to be done only once per URL.
2. Make sure to select atleast one event type. For testing, try checking all of them.
3. On the server, when you receive this call, you need to pass the JSON string received from server, to WebhookEvent::validateAndGetReceivedEvent() method, as shown below:

/**
 * This is one way to receive the entire body that you received from PayPal webhook. This is one of the way to retrieve that information. It could be different based on different frameworks you might be using.
 * Just uncomment the below line to read the data from actual request.
 */
/** @var String $bodyReceived */
$bodyReceived = file_get_contents('php://input');

// ### Validate Received Event Method
// Call the validateReceivedEvent() method with provided body, and apiContext object to validate
try {
    /** @var \PayPal\Api\WebhookEvent $output */
    $output = \PayPal\Api\WebhookEvent::validateAndGetReceivedEvent($bodyReceived, $apiContext);

    // $output would be of type WebhookEvent
    echo $output->toJSON();
} catch (\InvalidArgumentException $ex) {
    // This catch is based on the bug fix required for proper validation for PHP. Please read the note below for more details.
    // If you receive an InvalidArgumentException, please return back with HTTP 503, to resend the webhooks. Returning HTTP Status code [is shown here](http://php.net/manual/en/function.http-response-code.php). However, for most application, the below code should work just fine.
    http_response_code(503);
} catch (Exception $ex) {
    echo $ex->getMessage();
    exit(1);
}

NOTE

• Because of the secondary approach PHP SDK uses to validate webhooks, currently, it throws back InvalidArgumentException with message Webhook Event Id provided in the data is incorrect. This could happen if anyone other than PayPal is faking the incoming webhook data.\InvalidArgumentException

• This requires developers to ask webhook request sent from paypal to resend it at later time. This can be achieved by returning HTTP 503 Status code. More information on HTTP 503

• The above code shows the method used to achieve that. If for some reason, your application framework does not allow for direct settings to HTTP responses, please implement it in the way the application framework understands.