Anyone who learns your webhook URL can send requests to it. Turn on signing so your system can tell that a webhook really came from Hyfin and was not changed on the way. Signing follows the Standard Webhooks spec, so its verification libraries work as they are.
Create a signing secret for the site:
With an empty body, Hyfin creates a secret and returns it once, as data.secret. Store it somewhere safe. It cannot be read back later. You can send your own instead, as secret: whsec_ followed by 24 to 64 random bytes in base64. A secret you send is not returned.
Call the same endpoint again to replace the secret. The old secret keeps signing next to the new one for 24 hours, so you can switch your system over without rejecting webhooks. Set previous_secret_expires_in_hours to change that window, from 0 (stop using the old secret now) to 168 hours.
Shows whether signing and the custom header are turned on. It never returns a secret.
Stops signing and drops every secret for the site.
The simplest way is a Standard Webhooks library. They exist for JavaScript, Python, Go, Java, Ruby, PHP and .NET. Pass the raw body exactly as it arrived, before any JSON parsing.
import { Webhook } from 'standardwebhooks'
// Throws when the signature or timestamp is wrong.
const payload = new Webhook(process.env.WEBHOOK_SECRET).verify(rawBody, request.headers)
To check it yourself:
import crypto from 'node:crypto'
export function verifyWebhook(secret, headers, rawBody) {
const id = headers['webhook-id']
const timestamp = Number(headers['webhook-timestamp'])
if (!id || !Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 5 * 60) return false
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest()
return (headers['webhook-signature'] ?? '').split(' ').some(entry => {
const [version, signature = ''] = entry.split(',')
const received = Buffer.from(signature, 'base64')
return version === 'v1' && received.length === expected.length && crypto.timingSafeEqual(received, expected)
})
}
If your system can only check a fixed header, for example at an API gateway, Hyfin can send one header of your choice on every webhook. This works with or without signing, but signing is safer because the value never changes.
Send name and value. The value must be 16 to 2,048 visible ASCII characters, and may contain spaces in the middle. The name cannot start with webhook- or be a header every request already carries, such as Content-Type or Host.
Stops sending the header.