DigitalCX - Webhook helpers
The sdk-webhooks is a package that wraps DigitalCX webhooks inbound and outbound payloads into simple javascript objects. It supports Validation, Transaction and Context Variable webhooks.
Install and usage
Run npm install @cxco/sdk-webhooks
Then you can use the three main classes:
-
ValidationResponse
for handling validation webhooks -
TransactionResponse
for handling transaction (end slot) webhooks -
ContextResponse
for handling Context Variable webhooks
For instance in an express route handlers to extract 3 digits from the user input you could do:
const { ValidationResponse } = require('@cxco/sdk-webhooks')
const matchThreeNumbers = require('./utils/matchThreeNumbers')
/**
* Express middleware to handle the validation webhook and find 3 numbers in the user input
*
* @param {object} req
* @param {object} res
* @param {function} next
*/
module.exports = function findThreeNumbers (req, res, next) {
try {
// make sure the req.body JSON has already been parsed with the body-parse middleware
const slot = new ValidationResponse(req.body)
// make sure we are validating the current slot
if (slot.isCurrentSlot) {
const match = matchThreeNumbers(input)
if (match !== '') {
// this will set the value to the matched numbers
// and set the status of the slot to 'done'
slot.setValue(match)
}
}
// return the payload using the toModel method
res.send(slot.toModel())
} catch (error) {
// call the error handling middleware
next(error)
}
}
ValidationResponse
const slot = new ValidationResponse(req.body)
// check if it is the initial response
slot.initialRequest // boolean
// check if it si the current slot that is being validated
slot.isCurrentSlot // boolean
// set the value of the slot
slot.setValue('new value') // will also set the status to 'done'
// add to the metadata
slot.metadata.foo = 'bar'
// build the required response payload
slot.toModel()
Mock functions
There are three mock functions available to test your webhooks:
-
mockSlot
will mock the configuration of a slot including the set value, status and metadata. -
mockValidationPayload
to mock the full validation webhook payload. UsesmockSlot
to define thepayload.slot
object. -
mockTransationPayload
to mock the full transaction webhook payload. UsesmockSlot
to define the elements inpayload.slots
array.
You can use them in your tests like so:
const { mocks, ValidationResponse } = require('@cxco/sdk-webhooks').
describe('isCurrentSlot', () => {
it('is true when the current slot is the active one', () => {
const payload = mocks.mockValidationPayload({
inputSlotName: 'the current slot',
slot: mocks.mockSlot({ name: 'the current slot' })
})
const instance = new ValidationResponse(payload)
expect(instance.isCurrentSlot).toBe(true)
})
it('is false when current slot is not the active one', () => {
const payload = mocks.mockValidationPayload({
inputSlotName: 'the current slot',
slot: mocks.mockSlot({ name: 'another slot' })
})
const instance = new ValidationResponse(payload)
expect(instance.isCurrentSlot).toBe(false)
})
})
ContextResponse
ContextResponse wraps the inbound payload. The function setOutboundContextVariable
sets the value for a given context.
const { ContextResponse } = require('@cxco/sdk-webhooks')
//...
app.post('/context', function (req, res) {
const cxtResponse = new ContextResponse(req.body)
cxtResponse.setOutboundContextVariable("season", "summer")
// build the required response payload and send as an answer
res.send(cxtResponse.toModel())
})