@digitalocean/webhook-sdk

Getting Started

Install the package:

npm install @digitalocean/webhook-sdk

or

yarn add @digitalocean/webhook-sdk

Verifying a payload signature

Use Signature.parse and signature.verify to verify an incoming webhook payload request.

Important: Make sure to pass the body of the request to signature.verify raw without formatting it to avoid slight mismatches and thus failures to verify the signature. By default, your HTTP server might parse the incoming JSON and provide an object in the body. The example below uses express.raw specifically to prevent that.

const { Signature, HTTPHeaderSignature } = require('@digitalocean/webhook-sdk')
const express = require('express');
const { createServer } = require('http');

const app = express();
const server = createServer(app);

const SECRET = process.env.SIGNATURE_SECRET

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const signatureHeader = req.headers[HTTPHeaderSignature];
    const signature = Signature.parse(signatureHeader);
    signature.verify(req.body, SECRET);
    res.status(200).send('verified');
  } catch (error) {
    return res.status(401).send(`failed to verify: ${error.message}`)
  }
});


server.listen(8080, function () {
  console.log('Listening on http://0.0.0.0:8080');
});

Signing a payload using a secret

Use Signature.createSignature to sign a payload.

app.post('/sign', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const signature = Signature.createSignature({
      payload: req.body,
      secrets: [SECRET],
      timestamp: Date.now()
    })
    return res.status(200).send(signature.toString())
  } catch (error) {
    return res.status(500).send(`failed to sign payload: ${error.message}`, )
  }
})

Signature and Request Format

Header: do-signature
Format: t={ts},v1={sig}

• ts: The current unix timestamp at the time the request is made. This may change across retries.
  
• v1: Indicates the signature scheme version. Currently, only v1 is available.
  

Examples:

• one secret
  • t=1492774577,v1=5257a869e7ecee108d8bd
• two secrets
  • t=1492774577,v1=5257a869e7ecee108d8bd,v1=cee108d8bd5257a869e7e
• one secret, two scheme versions
  • t=1492774577,v2=1fe71593b0c,v1=5257a869e7ecee108d8bd
• two secrets, two scheme versions
  • t=1492774577,v2=1fe71593b0c,v2=3190e6d8151ac120,v1=5257a869e7ecee108d8bd,v1=cee108d8bd5257a869e7e

License

This package is licensed under the Apache License 2.0.

Copyright 2023 DigitalOcean.