Skip to content

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 ​

HeaderContains
webhook-idThe message's ID. A retry sends the same one, so use it to ignore duplicates.
webhook-timestampWhen the request was signed, in Unix seconds.
webhook-signaturev2a, and the signature in base64. While we change our key, one per key, separated by spaces.

Checking a request ​

  1. Reject it if webhook-timestamp is more than five minutes away from your clock.
  2. Join your endpoint ID, webhook-id, webhook-timestamp and the request body with full stops, and hash that with SHA-256. Use the body exactly as it arrived, before parsing it.
  3. Take each v2a, signature from webhook-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 its whpk_ prefix. The request is ours if one of them verifies.
  4. Handle each webhook-id only 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 ​

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.