Skip to content

atoms-studio/commercelayer-webhooks

Repository files navigation

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