Validating PayPal Webhooks Offline (Almost)

Update 4/9/2021: Now includes a Python example!

PayPal offers the abillity for you to receive webhooks for transaction notifications.  This isn’t exactly new — it was introduced with the REST APIs back in 2013(-ish?).  But for those of you still using IPN, you should know that webhooks has some big advantages over IPN.

First, webhooks provides a more structured way to find out exactly what happened.  Each webhook event includes an event_type — so you can figure out just by looking at that what happened.  Second, PayPal provides APIs to let you create webhooks, retrieve events, replay events, and even see samples of the different event types.  Third, you can have more than one webhook per account — this is a big advantage over IPN, which would only let you have one IPN listener per account.  There are more advantages, but that’s not what I want to focus on for this post.

As with IPN, there’s the question of “how do I know that this webhook event is genuine?”  PayPal has the Verify Webhook Signature API to do this — but what if I want to do it without making another API call?  There is actually a way to do this.

PayPal crytographically signs the webhook event when it’s sent to you — and (almost) all the information that you need to verify the signature (as well as the signature itself) are included in the HTTP post.  Let’s look at the different elements:

First, there are a number of HTTP headers that PayPal includes when it makes the post to your site:

• PAYPAL-TRANSMISSION-ID is a unique ID (more specifically, a UUID) for the transmission.
• PAYPAL-TRANSMISSION-TIME is the time when PayPal initiated the transmission of the webhook, in ISO 8601 format.
• PAYPAL-TRANSMISSION-SIG is the Base64-encoded signature.
• PAYPAL-CERT-URL is the URL to the certificate which corresponds to the private key that was used to generate the signature.
• PAYPAL-AUTH-ALGO is the algorithm that was used to generate the signature.  (I’ve only ever seen PayPal use SHA256withRSA, but it’s possible that PayPal might switch in the future if/when SHA256 is broken.)

And lastly, there’s the body of the HTTP post itself — the webhook JSON.

How do you validate the signature?  Well, the signature isn’t based off the body of the webhook itself; rather, it’s based off the following string:

<transmissionid>|<timestamp>|<webhookid>|<crc>

• <transmissionid> and <timestamp> are the verbatim values given in the PAYPAL-TRANSMISSION-ID and PAYPAL-TRANSMISSION-TIME HTTP headers, respectively.
• <webhookid> is the ID that PayPal assigned to your webhook when you created it.  You can find this a few different places:
  • If you used the Webhooks API to create the webhook, this would have been the value of /id in the response.
  • You can use the List All Webhooks API to see the webhooks you have registered.  You can grab the webhook ID from there.
  • You can also see your webhooks from developer.paypal.com.  (Go to the Dashboard, then the My Apps & Credentials page.  Scroll down to the REST API Apps section and find your REST app.  Click on it, then scroll down to the “Sandbox Webhooks” or “Live Webhooks” section.  The webhook ID will be displayed in the “Webhook ID” column.)

• <crc> is the CRC32 of the body of the HTTP post (e.g., the raw, unaltered webhook JSON), and expressed as a base 10, unsigned integer.

Let’s look at a quick example.  Suppose this is what PayPal posted to you.  (This is an actual webhook I received, albeit slightly modified:)

In this example:

• <transmissionid> would be 6e3b26a0-9287-11e7-ac1e-6b62a8a99ac4.
• <timestamp> would be 2017-09-05T22:13:22Z.  (Remember — use the exact value that PayPal passed to you.  Don’t try to change this into your local timezone or change its format.)
• <id> would be my webhook ID, which in this case is 2R269424P6803053B.
• <crc> would be 1330495958.

Which means that the string PayPal signed would be:

6e3b26a0-9287-11e7-ac1e-6b62a8a99ac4|2017-09-05T22:13:22Z|2R269424P6803053B|1330495958

The last thing to do is to verify the signature.

So far, we’ve been able to do everything without pulling in any external resources, but unfortunately that ends here.  To verify the signature, we need a copy of the certificate that corresponds to the private key that was used to generate the signature.  PayPal provided us a URL where we can fetch that certificate (in the PAYPAL-CERT-URL header) — we’ll need to fetch a copy of that.  Bad news is that means pulling in an outside resource (which will slow down the verification process); good news is that the certificates don’t change that often (in fact, I’ve only ever seen PayPal use one certificate), so you can cache the certificate for future use.

The only thing that’s left is to verify the signature against the string we formed above.  I won’t get into specifics on this — each language has their own way of pulling this off.  Java has built-in classes and methods that will help you out with this; for PHP, you can use the built-in OpenSSL functions to help you out.

If the signature verification is successful, and you trust the certificate that was used to sign the message, then you can be sure that the message you’re receiving is genuine.

Side note: there’s a weakness here in that CRC32 is used to hash the actual message body.  CRC32 isn’t a secure hashing algorithm (not sure it was ever meant to be), so I’m not sure why PayPal decided to use that instead of something like SHA256.  (Edit: I’m told something new is in the works.)

Anywho…I wrote a couple of example implementations.  Note that these examples don’t cache the certificates — you’ll need to figure out how to do that on your own.  But, feel free to use what I have.

First, a PHP example:

And second, a Java servlet (written for Apache Tomcat 8):

And finally, a third example written for Python 3. This example will need the cryptography library (pip install cryptography) and the requests library (pip install requests).