Class WebhookSigner

java.lang.Object

com.kingsrook.qqq.backend.core.utils.webhooks.WebhookSigner

public final class WebhookSigner
extends Object

Signs webhook requests in the Standard Webhooks format (https://www.standardwebhooks.com/).

The signed content is <id>.<timestamp>.<body>: the message id, a dot, the Unix timestamp in seconds, a dot, then the exact body bytes. The signature is HMAC-SHA256 with the secret's key, base64 encoded, and sent as v1,<base64>. During a secret rotation every active secret signs, and the signatures are separated by spaces, so a receiver holding either the old or the new secret accepts the request.

Headers: webhook-id, webhook-timestamp, webhook-signature.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	HEADER_ID
static final String	HEADER_SIGNATURE
static final String	HEADER_TIMESTAMP
static final String	VERSION_V1	The only signature scheme today: HMAC-SHA256.

Method Summary

Modifier and Type	Method	Description
static Map<String,String>	headers(String messageId, Instant timestamp, byte[] body, List<WebhookSecret> secrets)	The three signature headers for one request.
static String	sign(String messageId, long timestampSeconds, byte[] body, WebhookSecret secret)	One base64 HMAC-SHA256 signature over <id>.<timestamp>.<body>.
static String	signatureHeader(String messageId, long timestampSeconds, byte[] body, List<WebhookSecret> secrets)	The webhook-signature value: v1,<sig> per secret, space separated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

HEADER_ID

public static final String HEADER_ID

See Also:

• Constant Field Values

HEADER_TIMESTAMP

public static final String HEADER_TIMESTAMP

See Also:

• Constant Field Values

HEADER_SIGNATURE

public static final String HEADER_SIGNATURE

See Also:

• Constant Field Values

VERSION_V1

public static final String VERSION_V1

The only signature scheme today: HMAC-SHA256.

See Also:

• Constant Field Values

Method Details

headers

public static Map<String,String> headers(String messageId,
 Instant timestamp,
 byte[] body,
 List<WebhookSecret> secrets)

The three signature headers for one request.

Parameters:

messageId - the event id (stable across retries: it is the idempotency key)

timestamp - when this attempt is sent

body - the exact bytes that are sent

secrets - the active secrets (one, or two during a rotation)

signatureHeader

public static String signatureHeader(String messageId,
 long timestampSeconds,
 byte[] body,
 List<WebhookSecret> secrets)

The webhook-signature value: v1,<sig> per secret, space separated.

sign

public static String sign(String messageId,
 long timestampSeconds,
 byte[] body,
 WebhookSecret secret)

One base64 HMAC-SHA256 signature over <id>.<timestamp>.<body>.