Class WebhookHandler

java.lang.Object

com.fortemate.dicechess.runtime.WebhookHandler

public final class WebhookHandler
extends Object

Authenticates and dispatches DiceChess webhook deliveries to a BotStrategy.

The unsigned legacy version-1 ownership handshake is preserved. Version-2 verification challenges are authenticated against the pending key and return a cryptographic activation response proof. Game decisions are authenticated over the exact raw body under active and/or pending keys before any decision-specific state is read. A strategy runtime exception is converted to a bounded error response and its message is never returned to the caller.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	SIGNATURE_HEADER	Header carrying the hex HMAC-SHA256 signature (see Signatures).
static final String	TIMESTAMP_HEADER	Header carrying the delivery's Unix-epoch-seconds timestamp.

Constructor Summary

Constructors

Constructor	Description
WebhookHandler(WebhookHandler source, ResignPolicy resignPolicy)	Creates a handler identical to source except for its resign policy.
WebhookHandler(WebhookKeys keys, BotStrategy strategy)	Creates a handler with an immutable key configuration and without the GET /games/{id}/moves fallback.
WebhookHandler(WebhookKeys keys, String playApiBaseUrl, BotStrategy strategy)	Creates a handler with an immutable key configuration that fetches GET /games/{id}/moves when a turn's inline move tree is capped.
WebhookHandler(WebhookKeys keys, String playApiBaseUrl, BotStrategy strategy, ResignPolicy resignPolicy)	Creates a handler with an immutable key configuration and custom resign policy.
WebhookHandler(String secret, BotStrategy strategy)	Creates a handler with a single active secret and without the GET /games/{id}/moves fallback.
WebhookHandler(String secret, String playApiBaseUrl, BotStrategy strategy)	Creates a handler with a single active secret that fetches GET /games/{id}/moves when a turn's inline move tree is capped.
WebhookHandler(String secret, String playApiBaseUrl, BotStrategy strategy, ResignPolicy resignPolicy)	Creates a handler with a single active secret and custom resign policy.

Method Summary

Modifier and Type	Method	Description
Response	handle(Map<String,String> headers, String rawBody, long nowEpochSeconds)	Handles one webhook request.
WebhookKeys	keys()	Returns the immutable key configuration used by this handler.
ResignPolicy	resignPolicy()	Returns the resign policy used by this handler.

Methods inherited from class Object

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

Field Details

TIMESTAMP_HEADER

public static final String TIMESTAMP_HEADER

Header carrying the delivery's Unix-epoch-seconds timestamp.

See Also:

• Constant Field Values

SIGNATURE_HEADER

public static final String SIGNATURE_HEADER

Header carrying the hex HMAC-SHA256 signature (see Signatures).

See Also:

• Constant Field Values

Constructor Details

WebhookHandler

public WebhookHandler(String secret,
 BotStrategy strategy)

Creates a handler with a single active secret and without the GET /games/{id}/moves fallback.

Parameters:

secret - the webhook secret issued by the platform

strategy - the decision-oriented bot strategy

WebhookHandler

public WebhookHandler(String secret,
 String playApiBaseUrl,
 BotStrategy strategy)

Creates a handler with a single active secret that fetches GET /games/{id}/moves when a turn's inline move tree is capped. The fallback endpoint is public and needs no additional credential.

Parameters:

secret - the webhook secret issued by the platform

playApiBaseUrl - play-api's base URL; a trailing slash is tolerated

strategy - the decision-oriented bot strategy

WebhookHandler

public WebhookHandler(String secret,
 String playApiBaseUrl,
 BotStrategy strategy,
 ResignPolicy resignPolicy)

Creates a handler with a single active secret and custom resign policy.

Parameters:

secret - the webhook secret issued by the platform

playApiBaseUrl - play-api's base URL; a trailing slash is tolerated

strategy - the decision-oriented bot strategy

resignPolicy - the policy consulted before strategy dispatch

WebhookHandler

public WebhookHandler(WebhookKeys keys,
 BotStrategy strategy)

Creates a handler with an immutable key configuration and without the GET /games/{id}/moves fallback.

Parameters:

keys - the active and/or pending webhook keys

strategy - the decision-oriented bot strategy

WebhookHandler

public WebhookHandler(WebhookKeys keys,
 String playApiBaseUrl,
 BotStrategy strategy)

Creates a handler with an immutable key configuration that fetches GET /games/{id}/moves when a turn's inline move tree is capped. The fallback endpoint is public and needs no additional credential.

Parameters:

keys - the active and/or pending webhook keys

playApiBaseUrl - play-api's base URL; a trailing slash is tolerated

strategy - the decision-oriented bot strategy

WebhookHandler

public WebhookHandler(WebhookKeys keys,
 String playApiBaseUrl,
 BotStrategy strategy,
 ResignPolicy resignPolicy)

Creates a handler with an immutable key configuration and custom resign policy.

Parameters:

keys - the active and/or pending webhook keys

playApiBaseUrl - play-api's base URL; a trailing slash is tolerated

strategy - the decision-oriented bot strategy

resignPolicy - the policy consulted before strategy dispatch

WebhookHandler

public WebhookHandler(WebhookHandler source,
 ResignPolicy resignPolicy)

Creates a handler identical to source except for its resign policy.

Used to derive a draining handler from a running one without rebuilding, or losing, the keys, the play-api base URL and the strategy the application configured.

Parameters:

source - the handler to copy

resignPolicy - the policy the copy consults before strategy dispatch

Method Details

keys

public WebhookKeys keys()

Returns the immutable key configuration used by this handler.

Returns:

the webhook keys

resignPolicy

public ResignPolicy resignPolicy()

Returns the resign policy used by this handler.

Returns:

the resign policy

handle

public Response handle(Map<String,String> headers,
 String rawBody,
 long nowEpochSeconds)

Handles one webhook request.

Parameters:

headers - the request headers; lookup is case-insensitive

rawBody - the request body exactly as received

nowEpochSeconds - the verifier's current Unix epoch time in seconds

Returns:

status 200 for a successful handshake/decision, 400 for a malformed or unknown envelope, 401 for a missing/expired/wrong signature, or 500 for a strategy failure