Webhooks > Security and Handling


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.


Headers on every webhook

  • webhook-id The id of this message. It stays the same on every retry, so use it to spot a webhook you already handled.
  • webhook-timestamp When this attempt was sent, in seconds since 1970 (Unix time).
  • webhook-signature Sent only when signing is turned on. It holds v1, and then the signature. While an old secret is still active after a change, there are two signatures, separated by a space.

Turn on signing

Create a signing secret for the site:

POST
{base_url}/api/v4/site/{site_id}/webhook/signingSecret/rotate

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.

Change the secret

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 previousSecretExpiresInHours to change that window, from 0 (stop using the old secret now) to 168 hours.

Check or turn off signing

GET
{base_url}/api/v4/site/{site_id}/webhook/security

Shows whether signing and the custom header are turned on. It never returns a secret.

POST
{base_url}/api/v4/site/{site_id}/webhook/signingSecret/remove

Stops signing and drops every secret for the site.


Verify a webhook

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.

With the standardwebhooks library
			
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:

  1. Reject the webhook if webhook-timestamp is more than a few minutes from now. This stops an old webhook from being sent to you again.
  2. Join webhook-id, webhook-timestamp and the raw body with a period between each.
  3. Remove whsec_ from the start of your secret and decode the rest from base64. That is the key.
  4. Sign the joined text with HMAC-SHA256 using that key, and encode the result in base64.
  5. Accept the webhook if it matches any v1, entry in webhook-signature. Compare in constant time.
Without a library (Node.js)
			
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)
	})
}


		

Custom header

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.

POST
{base_url}/api/v4/site/{site_id}/webhook/authHeader/set

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.

POST
{base_url}/api/v4/site/{site_id}/webhook/authHeader/remove

Stops sending the header.


Handling webhooks

  • Answer fast. Reply with any 2xx status as soon as the webhook is safely stored, then do the slow work afterwards. A webhook with no 2xx reply within 30 seconds counts as failed and is sent again.
  • Expect repeats. The same webhook can arrive more than once. Skip any webhook-id you already handled.
  • Expect them out of order. A retried webhook can arrive after a newer one for the same record. When order matters, read the record back with its Get endpoint.
  • Check the signature before you act on a webhook.

See Webhooks > Introduction for when retries happen.