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 requestrespondOnError
(boolean, optional, default: true) - whether or not the request should automatically respond to the request with an error, or (iffalse
) 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.