Woocommerce Webhooks Secret Key

Let’s admit it, I spend too much time on Facebook. In my defense, it’s not all spent looking at memes. I have plenty of WordPress support groups that I follow.

One of the problems with Facebook is that it’s not spidered well by Google. And most groups require that you login and be a member to see the posts. Facebook’s own search system is practically useless. The end result is much of the knowledge is lost.

There was a question in the Advanced Woocommerce group about what the Webhook “Secret” field configured in the Woocommerce Webhooks dashboard area really means.

The woocommerce docs can be really poor. In this case it lacks important details such as what kind of hash is used and how to use this secret in your application receiving the hook. With no guidance on the value to put in this field, what is a user supposed to do?

(If anyone from Automattic or woocommerce is reading this, a link from the end user docs to tech docs would be super helpful for obscurely defined configuration fields like this one.)

In addition to the Woo dot-com docs and developer codex, there are little-known WC developer docs on github. These are designed for the Woocommerce REST API.

My first nugget of wisdom for WordPress developers: When the woocommerce.com PHP docs suck, sometimes more details can be found in the REST docs, as was the case here.

In my attempt to help the next person with the same question, here is my answer on how the woocommerce webhooks secret field is used. (links to this page are encouraged)

The Meaning Of The Woocommerce Webhooks Secret Field

The secret has a little better description on the github REST API docs than the woocmmerce.com end user docs. It is documented as the “Secret key used to generate a hash of the delivered webhook and provided in the request headers.”

Later on in the github docs is a description of how the hash is received – as a HTTP header in the webhook response. “X-WC-Webhook-Signature – A base64 encoded HMAC-SHA256 hash of the payload”.

You have to know a little bit about cryptography to understand this.

A hashed MAC is used to verify the data integrity and the authentication of a message. The SHA256 HMAC algorithm is satisfied by a 32 byte key. We’re talking a full entropy key (complete random characters in the key). The maximum key size is 64 bytes. Anything larger is reduced to 32 bytes.

You can use this php code to generate a base64 encoded hash MAC on your receiving side to compare with the X-WC-Webhook-Signature value in the HTTP header in order to validate the message. If your encoded hash signature and the one in the HTTP header match then you are able to assume this is a valid response from the woocommerce site.

$yourHashSig = base64_encode(hash_hmac('sha256', $request_body, $secret, true));

The secret used here is the same secret value set on the woocommerce webhooks configuration page.

The hooks are not replayed. If you miss it, it’s gone. Webhooks, unlike an API, are 1 way and don’t require a response.

OnSiteWP WordPress Support Plug

OnSiteWP is different from other WordPress support companies in that we have experienced WordPress developers on staff to answer questions when Google search fails you. As part of our 1-time WordPress Fix It service, we will be happy to explain an poorly documented plugin field to you.

If you have developed a lot of sites and don’t want to be responsible for plugin updates or if the site gets hacked, our WordPress maintenance affiliate program may be of interest to you.