README.md

Commerce Layer webhooks

Verify and parse Commerce Layer webhooks.

Installation

npm i commercelayer-webhooks

yarn add commercelayer-webhooks

Usage

Pass the request object along with the secret key provided by the Commerce Layer webhook interface.

const Webhook = require('commercelayer-webhooks')

/**
 * AWS Lambda / Netlify function
 */
module.exports = async function(event, context) {
  const { topic, resource } = await Webhook.handle(event, 'webhook secret')
  // ...handle topic and resource
}

/**
 * Express
 */
app.get('/webhooks', async (req, res) => {
  const { topic, resource } = await Webhook.handle(req, 'webhook secret')
  // ...handle topic and resource
})

For more examples with different frameworks, check out the examples folder

Signature verification

Signature verification is enabled by default and a SignatureVerificationError will be thrown if the verification process fails. You can catch the error to handle the failure manually.

const Webhook = require('commercelayer-webhooks')

module.exports = async function(event, context) {

  try {
    const { topic, resource } = await Webhook.handle(event, 'webhook secret')
    // ...handle topic and resource
  } catch ((err) => {
    if (error instanceof Webhook.SignatureVerificationError) {
      return {
        status: 400,
        body: error.message,
      }
    }

    // Throw the error again if not a SignatureVerificationError
    throw err
  })
}

Skipping signature verification

You can skip signature verification by passing a third argument as false to the handler.

const Webhook = require('commercelayer-webhooks')

module.exports = async function(event, context) {

  const { topic, resource } = await Webhook.handle(event, 'webhook secret', false)
  // ...handle topic and resource
}

API

Webhook.handle(request, secret, verify = true)

Argument	Type	Description
request	Object	The request object that contains the webhook information. It needs to have a headers property containing all the request headers, and at least one of body, rawBody or payload properties containing the webhook payload as string.
secret	String	The webhook secret found in the Commerce Layer webhook interface.
verify	Boolean	Enable or disable signature verification. Defaults to true.

The function returns a promise that resolves with the following object:

{
  topic: 'topic sent by the webhook',
  resource: {
    // An object representing a Commerce Layer resource. 
    // The object properties depend on the topic received
  }
}

---

Webhook.SignatureVerificationError

This is the error thrown when the signature verification fails. It contains the following properties:

Name	Type	Description
message	String	The standard error messsage. It is always "Signature mismatch"
signature	String	The signature sent by the webhook.
body	String	The body sent by the webhook.

Contributing

Please read CONTRIBUTING.md

License

MIT