@sanity/webhook

Toolkit for dealing with GROQ-powered webhooks delivered by Sanity.io

Usage no npm install needed!

<script type="module">
  import sanityWebhook from 'https://cdn.skypack.dev/@sanity/webhook';
</script>

README

@sanity/webhook

Toolkit for dealing with GROQ-powered webhooks delivered by Sanity.io.

Installing

$ npm install @sanity/webhook

Usage

// ESM / TypeScript
import {isValidSignature} from '@sanity/webhook'

// CommonJS
const {isValidSignature} = require('@sanity/webhook')

Usage with Express.js (or similar)

import express from 'express'
import bodyParser from 'body-parser'
import {requireSignedRequest} from '@sanity/webhook'

express()
  .use(bodyParser.json())
  .post('/hook', requireSignedRequest({secret: process.env.MY_WEBHOOK_SECRET}))
  .listen(1337)

Usage with Next.js

// pages/api/hook.js
import {isValidRequest} from '@sanity/webhook'

const secret = process.env.MY_WEBHOOK_SECRET

export default function handler(req, res) {
  if (!isValidRequest(req, secret)) {
    res.status(401).json({success: false, message: 'Invalid signature'})
    return
  }

  doSomeMagicWithPayload()
  res.json({success: true})
}

Documentation

Functions

requireSignedRequest

requireSignedRequest(options: SignatureMiddlewareOptions): RequestHandler

Returns an express/connect-compatible middleware which validates incoming requests to ensure they are correctly signed.

Options:

  • secret (string, required) - the secret to use for validating the request
  • respondOnError (boolean, optional, default: true) - whether or not the request should automatically respond to the request with an error, or (if false) pass the error on to the next registered error middleware.

assertValidSignature

assertValidSignature(stringifiedPayload: string, signature: string, secret: string): void

Asserts that the given payload and signature matches and is valid, given the specified secret. If it is not valid, the function will throw an error with a descriptive message property.

Note: The payload should be a JSON-encoded string, eg if you have a plain old Javascript object, pass it to JSON.stringify() before passing it to this function.

isValidSignature

isValidSignature(stringifiedPayload: string, signature: string, secret: string): boolean

Returns whether or not the given payload and signature matches and is valid, given the specified secret. On invalid, missing or mishaped signatures, this function will return false instead of throwing.

Note: The payload should be a JSON-encoded string, eg if you have a plain old Javascript object, pass it to JSON.stringify() before passing it to this function.

assertValidRequest

assertValidRequest(request: ConnectLikeRequest, secret: string): void

Asserts that the given request has a request body which matches the received signature, and that the signature is valid given the specified secret. If it is not valid, the function will throw an error with a descriptive message property.

Note: The request object passed should have a parsed body property, eg if you're using express or connect, make sure you have a JSON body-parser middleware registered for the route.

isValidRequest

isValidRequest(request: ConnectLikeRequest, secret: string): boolean

Returns whether or not the given request has a request body which matches the received signature, and that the signature is valid given the specified secret.

Note: The request object passed should have a parsed body property, eg if you're using express or connect, make sure you have a JSON body-parser middleware registered for the route.

License

MIT-licensed. See LICENSE.