Status page webhooks
When you subscribe a generic webhook to updates on our status page, your endpoint gets every notification as an HTTPS POST with a JSON body. Each request is signed with our Ed25519 key, the way the Standard Webhooks spec describes v2a signatures, so you can check that it came from NeoProtect and was not changed on the way.
What you need
- Our public key, starting with
whpk_. It is the same for every subscriber. - Your endpoint ID, starting with
ep_. Each subscription has its own, and it never changes.
Both are on your subscription's manage page, which the link in the first request to your endpoint opens. Save them in your receiver's settings.
NOTE
When we change our key, the manage page lists two public keys for a while, and every request carries a signature for each of them. Add the new key to your settings, and remove the old one once the manage page no longer lists it.
Headers
| Header | Contains |
|---|---|
webhook-id | The message's ID. A retry sends the same one, so use it to ignore duplicates. |
webhook-timestamp | When the request was signed, in Unix seconds. |
webhook-signature | v2a, and the signature in base64. While we change our key, one per key, separated by spaces. |
Checking a request
- Reject it if
webhook-timestampis more than five minutes away from your clock. - Join your endpoint ID,
webhook-id,webhook-timestampand the request body with full stops, and hash that with SHA-256. Use the body exactly as it arrived, before parsing it. - Take each
v2a,signature fromwebhook-signature, decode what follows the comma from base64, and verify it with Ed25519 over the 32-byte hash. Try each public key you saved: the base64 after itswhpk_prefix. The request is ours if one of them verifies. - Handle each
webhook-idonly once.
WARNING
Take the endpoint ID from your settings, never from a request. It is what stops a request we sent to someone else from passing your check.
Example in Node.js
import { createHash, createPublicKey, verify } from 'node:crypto';
// Both from your subscription's manage page.
const ENDPOINT_ID = 'ep_…';
const PUBLIC_KEYS = ['whpk_…'].map((key) => {
const x = Buffer.from(key.slice(5), 'base64').toString('base64url');
const jwk = { kty: 'OKP', crv: 'Ed25519', x };
return createPublicKey({ key: jwk, format: 'jwk' });
});
/** `body`: the raw request body (Buffer or string), not parsed JSON. */
export function isFromNeoProtect(headers, body) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
// More than five minutes off, or no timestamp at all: reject.
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!id || !(age <= 300)) return false;
const hash = createHash('sha256')
.update(`${ENDPOINT_ID}.${id}.${timestamp}.`)
.update(body)
.digest();
return (headers['webhook-signature'] ?? '')
.split(' ')
.filter((sig) => sig.startsWith('v2a,'))
.map((sig) => Buffer.from(sig.slice(4), 'base64'))
.some((sig) =>
PUBLIC_KEYS.some((key) => verify(null, hash, key, sig)),
);
}Slack, Microsoft Teams and Discord
Messages to these services are not signed. The service itself accepts posts only from whoever has the webhook URL, so keep that URL private.