bookclerk_plugin_manifest::webhooks
[[webhooks]]: inbound HTTP endpoints the host serves for a plugin.
The host serves each declared webhook at a secret per-instance URL under
the library's public origin, outside operator auth. Before anything is
stored it enforces the row's body cap, rate limit and signature rule; a
verified request is stored and answered at once, and the plugin reads
stored deliveries through its WEBHOOKS binding (see
docs/adr/storage-destinations.md, decision 6).
Every limit has a hard ceiling here, and the signature rule is required:
a plugin that takes unsigned requests says scheme = "none".
| Item | Kind | Summary |
|---|---|---|
WebhookManifest |
struct | One [[webhooks]] row. |
HmacSignature |
struct | An HMAC-SHA256 signature rule. |
WebhookSignature |
enum | How the host checks that a request came from the sender. |
SignatureEncoding |
enum | How a signature digest is written in its header. |
validate_webhooks |
function | Checks every [[webhooks]] row. |
WEBHOOKS_BINDING |
constant | The binding name a plugin with [[webhooks]] receives; fixed, so no other binding may take it. |
MAX_WEBHOOKS |
constant | Most [[webhooks]] rows one plugin may declare. |
MAX_WEBHOOK_NAME_LEN |
constant | Longest webhook name in bytes. |
DEFAULT_WEBHOOK_MAX_BODY_BYTES |
constant | Default body cap in bytes (64 KiB). |
MAX_WEBHOOK_BODY_BYTES |
constant | Largest body cap a row may declare, in bytes (1 MiB). |
DEFAULT_WEBHOOK_RATE_PER_MINUTE |
constant | Default request rate per minute for one instance's webhook. |
MAX_WEBHOOK_RATE_PER_MINUTE |
constant | Highest request rate per minute a row may declare. |
DEFAULT_WEBHOOK_RETENTION_SECS |
constant | Default time a stored delivery waits for the plugin, in seconds (1 day). |
MAX_WEBHOOK_RETENTION_SECS |
constant | Longest time a stored delivery may wait, in seconds (7 days). |
MAX_WEBHOOK_HEADERS |
constant | Most request headers a row may keep with each delivery. |
MAX_WEBHOOK_HEADER_NAME_LEN |
constant | Longest header name a row may name, in bytes. |
MAX_WEBHOOK_SIGNATURE_PREFIX_LEN |
constant | Longest signature prefix, in bytes. |
bookclerk_plugin_abi::webhooks::is_valid_webhook_header_nameasis_valid_header_namebookclerk_plugin_abi::webhooks::is_valid_webhook_name
pub struct WebhookManifest {
pub name: String,
pub max_body_bytes: u32,
pub rate_per_minute: u32,
pub retention_secs: u32,
pub headers: Vec<String>,
pub signature: WebhookSignature,
}
One [[webhooks]] row.
Fields
name: URL path segment and the name the binding uses ([a-z0-9][a-z0-9-]*, at mostMAX_WEBHOOK_NAME_LENbytes), unique within the plugin.max_body_bytes: Largest body the host accepts, in bytes (defaultDEFAULT_WEBHOOK_MAX_BODY_BYTES, at mostMAX_WEBHOOK_BODY_BYTES); a larger one is refused with 413.rate_per_minute: Requests per minute the host accepts for one instance (defaultDEFAULT_WEBHOOK_RATE_PER_MINUTE, at mostMAX_WEBHOOK_RATE_PER_MINUTE); more are refused with 429.retention_secs: Seconds a stored delivery waits for the plugin before it is dropped and counted as missed (defaultDEFAULT_WEBHOOK_RETENTION_SECS, at mostMAX_WEBHOOK_RETENTION_SECS).headers: Lowercase request header names kept with each delivery, besidescontent-type, which is always kept. Credential and hop headers are refused.signature: The check the host runs before storing a request.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct HmacSignature {
pub header: String,
pub prefix: String,
pub encoding: SignatureEncoding,
pub secret_setting: String,
}
An HMAC-SHA256 signature rule.
Fields
header: Lowercase header that carries the signature.prefix: Text before the digest in the header value (for examplev1=); empty when the value is the digest alone.encoding: How the digest is written.secret_setting: Key of atype = "secret"[[settings]]entry holding the shared key. The host reads it; the plugin never needs it.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum WebhookSignature {
None,
HmacSha256(HmacSignature),
}
How the host checks that a request came from the sender.
Variants
None: No check: every request within the caps is stored. The plugin must treat deliveries as untrusted hints.HmacSha256: HMAC-SHA256 of the raw body under a sealed plugin setting, carried in one header as<prefix><digest>.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum SignatureEncoding {
Hex,
Base64,
}
How a signature digest is written in its header.
Variants
Hex: Lowercase or uppercase hexadecimal.Base64: Standard base64 with padding.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub fn validate_webhooks(
rows: &[WebhookManifest],
is_secret_setting: impl Fn(&str) -> bool,
) -> Result<()>
Checks every [[webhooks]] row.
rows- the declared webhooks.is_secret_setting- whether a[[settings]]key names atype = "secret"entry.
Names the first row with a bad name, an out-of-range limit, a header the host cannot keep, or a signature rule that does not resolve.
pub const WEBHOOKS_BINDING: &str = "WEBHOOKS";
The binding name a plugin with [[webhooks]] receives; fixed, so no
other binding may take it.
pub const MAX_WEBHOOKS: usize = 8;
Most [[webhooks]] rows one plugin may declare.
pub const MAX_WEBHOOK_NAME_LEN: usize = _;
Longest webhook name in bytes.
pub const DEFAULT_WEBHOOK_MAX_BODY_BYTES: u32 = _;
Default body cap in bytes (64 KiB).
pub const MAX_WEBHOOK_BODY_BYTES: u32 = bookclerk_plugin_abi::MAX_WEBHOOK_BODY_BYTES;
Largest body cap a row may declare, in bytes (1 MiB).
pub const DEFAULT_WEBHOOK_RATE_PER_MINUTE: u32 = 60;
Default request rate per minute for one instance's webhook.
pub const MAX_WEBHOOK_RATE_PER_MINUTE: u32 = 600;
Highest request rate per minute a row may declare.
pub const DEFAULT_WEBHOOK_RETENTION_SECS: u32 = 86_400;
Default time a stored delivery waits for the plugin, in seconds (1 day).
pub const MAX_WEBHOOK_RETENTION_SECS: u32 = _;
Longest time a stored delivery may wait, in seconds (7 days).
pub const MAX_WEBHOOK_HEADERS: usize = _;
Most request headers a row may keep with each delivery.
pub const MAX_WEBHOOK_HEADER_NAME_LEN: usize = bookclerk_plugin_abi::webhooks::MAX_WEBHOOK_HEADER_NAME_BYTES;
Longest header name a row may name, in bytes.
pub const MAX_WEBHOOK_SIGNATURE_PREFIX_LEN: usize = 16;
Longest signature prefix, in bytes.
Generated from crates/bookclerk-plugin-manifest at main · View as Markdown