5

Upon integrating the smart button of Paypal I have issues to verify webhook notifications sent by Paypal. The examples I have found are either outdated or do not work.

Is there a way to verify the webhook notifications, ideally in a DIY way (ie. without having to use the bulky and complex Paypal API)?

4 Answers 4

7

To the best of my knowledge, this code is only one that actually works. All other examples I have found on stack overflow will not work because instead of passing the ID of the webhook itself when composing the signature string, they use the ID of the webhook event, thus the verify will fail.

The webhook ID will be generated once you add the webhook in the developer backend of Paypal. After creation of the webhook you will see its id in the list of installed webhooks.

The rest is pretty straight forward: We get the headers and the HTTP body and compose the signature using Paypal's recipe:

To generate the signature, PayPal concatenates and separates these items with the pipe (|) character.

"These items" are: The transmission id, the transmission date, the webhook id and a CRC over the HTTP body. The first two can be found in the header of the request, the webhook id in the developer backend (of course, that id will never change), the CRC is calculated like shown below.

The certificate's location is in the header, too, so we load it and extract the private key.

Last thing to watch out for: The name of the algorithm provided by Paypal (again in a header field) is not exactly the same as understood by PHP. Paypal calls it "sha256WithRSA" but openssl_verify will expect "sha256WithRSAEncryption".

// get request headers
$headers=apache_request_headers();

// get http payload
$body=file_get_contents('php://input');

// compose signature string: The third part is the ID of the webhook ITSELF(!),
// NOT the ID of the webhook event sent. You find the ID of the webhook
// in Paypal's developer backend where you have created the webhook
$data=
    $headers['Paypal-Transmission-Id'].'|'.
    $headers['Paypal-Transmission-Time'].'|'.
    '[THE_ID_OF_THE_WEBHOOK_ACCORDING_TO_DEVELOPER_BACKEND]'.'|'.
    crc32($body);

// load certificate and extract public key
$pubKey=openssl_pkey_get_public(file_get_contents($headers['Paypal-Cert-Url']));
$key=openssl_pkey_get_details($pubKey)['key'];

// verify data against provided signature 
$result=openssl_verify(
    $data,
    base64_decode($headers['Paypal-Transmission-Sig']),
    $key,
    'sha256WithRSAEncryption'
);

if ($result==1) {
    // webhook notification is verified
    ...
}
elseif ($result==0) {
    // webhook notification is NOT verified
    ...
}
else {
    // there was an error verifying this
    ...
}
4
  • 1
    A bad actor could send you a transmission with their own Cert URL and you'd load their cert, and thus their message would authenticate. Probably should verify root domain is paypal.com
    – Paul S
    Commented Jan 24, 2022 at 23:37
  • Be careful you may run into crc32 issues on the body: php.net/manual/en/function.crc32.php
    – Paul S
    Commented Jan 25, 2022 at 4:09
  • @PaulS I think, bad actor must know your THE_ID_OF_THE_WEBHOOK_ACCORDING_TO_DEVELOPER_BACKEND. If this does not leak from you, you are safe. Commented Nov 17, 2022 at 9:00
  • if webhook_id is supposed to be secret, then paypal would have said so: developer.paypal.com/api/rest/reference/…
    – Paul S
    Commented Nov 18, 2022 at 18:37
6

Answering this for nodejs, as there are subtle security issues and some missing logic in original (but very helpful) answer. This answer addresses the following issues:

  1. Someone putting in their own URL and thereby getting authentication of their own requests
  2. CRC needs to be an unsigned integer, not a signed integer.
  3. NodeJs < 17.0 is missing some built in X509 functionality.
  4. Ideally one should validate the signing cert with the built in cert chain but NodeJS < 17.0 can't do this easily AFAICT. The trust model relies on TLS and the built in nodejs trust chain for the cert fetch URL and not the returned cert from cert URL , which is probably good enough.
const forge = require('node-forge');
const crypto = require('crypto')
const CRC32 = require('crc-32');
const axios = require('axios');


  const transmissionId = paypalSubsEvent.headers['PAYPAL-TRANSMISSION-ID'];
  const transmissionTime = paypalSubsEvent.headers['PAYPAL-TRANSMISSION-TIME'];
  const signature = paypalSubsEvent.headers['PAYPAL-TRANSMISSION-SIG'];
  const webhookId = '<your webhook ID from your paypal dev. account>';
  const url = paypalSubsEvent.headers['PAYPAL-CERT-URL'];
  const bodyCrc32 = CRC32.str(paypalSubsEvent.body);  
  const unsigned_crc = bodyCrc32 >>> 0;     // found by trial and error

  // verify domain is actually paypal.com, or else someone
  // could spoof in their own cert
  const urlObj = new URL(url);
  if (!urlObj.hostname.endsWith('.paypal.com')) {
    throw new Error(
      `URL ${certUrl} is not in the domain paypal.com, refusing to fetch cert for security reasons`);
  }
  const validationString =
    transmissionId + '|'
    + transmissionTime + '|'
    + webhookId + '|'
    + unsigned_crc;

  const certResult = await axios.get(url);   // Trust TLS to check the URL is really from *.paypal.com
  const cert = forge.pki.certificateFromPem(certResult.data);
  const publicKey = forge.pki.publicKeyToPem(cert.publicKey)
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(validationString);
  verifier.end();
  const result = verifier.verify(publicKey, signature, 'base64');
  console.log(result);

0

You can use the following steps with Paypal API's

  1. Create App and get the Client ID and Secret from the Developer dashboard
  2. Create Webhook inside App and get a webhook ID

Implementation PayPal API's https://www.postman.com/paypal/workspace/paypal-public-api-workspace/collection/19024122-92a85d0e-51e7-47da-9f83-c45dcb1cdf24?action=share&creator=22959279

  1. Get the new Access token with help of Client ID and Secret, every time connect with PayPal.

4.Use the webhook Id, Access Token, and request Headers to verify the Webhook

 try{
    $json = file_get_contents('php://input');
        $data = json_decode($json);
        $paypalmode = ($this->dev_mode == 0) ? '' : '.sandbox';
        $API_Endpoint = 'https://api-m' . $paypalmode . '.paypal.com/v1/';
    //step-01 get token        
        $res_token = getToken($API_Endpoint);//get Token mention in above postman link
    //step-02 validate webhook
        $webhook_id = 'XXXXXX';
        $post_data = array(
            "webhook_id" => $webhook_id ,
            "transmission_id" => $_SERVER['HTTP_PAYPAL_TRANSMISSION_ID'],
            "transmission_time" => $_SERVER['HTTP_PAYPAL_TRANSMISSION_TIME'],
            "cert_url" => $_SERVER['HTTP_PAYPAL_CERT_URL'],
            "auth_algo" => $_SERVER['HTTP_PAYPAL_AUTH_ALGO'],
            "transmission_sig" => $_SERVER['HTTP_PAYPAL_TRANSMISSION_SIG'],
            "webhook_event" => $data
        );
        $res = verifyWebhook($API_Endpoint . 'notifications/verify-webhook-signature',
                $res_token['access_token'], $post_data);//use postman 'verify-webhook-signature' api mention in webhook section
        if (isset($res->verification_status) && $res->verification_status == 'SUCCESS') {
         //success
       }else{
         //failure
       }
   } catch (Exception $ex) {
        //error
   }
-1

Responding to this to save potential headaches but the above example does not work because an authentication token is needed to be sent along with your get request for the cert file "file_get_contents($header['Paypal-Cert-Url'])" will not work on its own.

Simply include your authentication token in the header and it'll work.

2
  • I use this code since mid 2020 exactly like shown and it definitely works like shown. 100 percent. Commented Mar 2, 2021 at 8:07
  • I just used curl to access https://api.sandbox.paypal.com/v1/notifications/certs/CERT-360caa42-fca2a594-7a8abba8 without any authentication tokens.
    – Paul S
    Commented Jan 24, 2022 at 22:42

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.