An extensible system empowers businesses to respond to emerging challenges efficiently. OrderCloud ensures extensibility, and Webhooks is one of the common approaches available to extend OrderCloud. Webhooks are user-defined HTTP callbacks, which invoke your own HTTP endpoints that performs custom logic, whenever the associated OrderCloud API endpoint is triggered. This introduces the need for validating the authenticity of the call within your HTTP endpoint, to ensure it is from OrderCloud.
For this purpose, OrderCloud includes a request header, ‘x-oc-hash’, with every request sent to the HTTP endpoint URL. This header holds the Base64 encoded hash of the incoming request’s raw body, hashed using HMAC(Hash-based Message Authentication Code) SHA-256 algorithm with the Webhook Secret(specified in OrderCloud portal during Webhook creation).
When building apps using Typescript/Javascript, this value can be comfortably verified using the new OrderCloud Javascript Catalyst npm package.
The npm package can be installed using the below command,
npm i @ordercloud/catalyst
This npm package expects a variable, OC_WEBHOOK_HASH_KEY, in your configuration, with the Webhook Secret as its value. The isOcHashValid method of the Catalyst, when invoked with the incoming Webhook Request and optionally the Webhook Secret, validates and returns a promise that resolves to a boolean value which indicates the authentication status,
The Webhook Secret must be passed as an input parameter to isOcHashValid method if it is different from what is specified in settings for ‘OC_WEBHOOK_HASH_KEY’.
You may benefit from withOcWebhookAuth, withOcErrorHandler methods of Javascript Catalyst when using express.js, next.js frameworks. Here are some examples that can be referred, https://github.com/ordercloud-api/ordercloud-javascript-catalyst
For security reasons, the webhook secret(s) must be kept confidential and shouldn’t be part of the codebase. It is recommended to store it in secure locations like Azure App Configuration, Azure Key Vault, etc.