@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.

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.