bookclerk_plugin_manifest::webhooks

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

[[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.

Re-exports

Structs

WebhookManifest

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

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

HmacSignature

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 example v1=); empty when the value is the digest alone.
  • encoding: How the digest is written.
  • secret_setting: Key of a type = "secret" [[settings]] entry holding the shared key. The host reads it; the plugin never needs it.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

Enums

WebhookSignature

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

SignatureEncoding

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

Functions

validate_webhooks

pub fn validate_webhooks(
    rows: &[WebhookManifest],
    is_secret_setting: impl Fn(&str) -> bool,
) -> Result<()>

Checks every [[webhooks]] row.

Arguments

  • rows - the declared webhooks.
  • is_secret_setting - whether a [[settings]] key names a type = "secret" entry.

Errors

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.

Constants

WEBHOOKS_BINDING

pub const WEBHOOKS_BINDING: &str = "WEBHOOKS";

The binding name a plugin with [[webhooks]] receives; fixed, so no other binding may take it.

MAX_WEBHOOKS

pub const MAX_WEBHOOKS: usize = 8;

Most [[webhooks]] rows one plugin may declare.

MAX_WEBHOOK_NAME_LEN

pub const MAX_WEBHOOK_NAME_LEN: usize = _;

Longest webhook name in bytes.

DEFAULT_WEBHOOK_MAX_BODY_BYTES

pub const DEFAULT_WEBHOOK_MAX_BODY_BYTES: u32 = _;

Default body cap in bytes (64 KiB).

MAX_WEBHOOK_BODY_BYTES

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).

DEFAULT_WEBHOOK_RATE_PER_MINUTE

pub const DEFAULT_WEBHOOK_RATE_PER_MINUTE: u32 = 60;

Default request rate per minute for one instance's webhook.

MAX_WEBHOOK_RATE_PER_MINUTE

pub const MAX_WEBHOOK_RATE_PER_MINUTE: u32 = 600;

Highest request rate per minute a row may declare.

DEFAULT_WEBHOOK_RETENTION_SECS

pub const DEFAULT_WEBHOOK_RETENTION_SECS: u32 = 86_400;

Default time a stored delivery waits for the plugin, in seconds (1 day).

MAX_WEBHOOK_RETENTION_SECS

pub const MAX_WEBHOOK_RETENTION_SECS: u32 = _;

Longest time a stored delivery may wait, in seconds (7 days).

MAX_WEBHOOK_HEADERS

pub const MAX_WEBHOOK_HEADERS: usize = _;

Most request headers a row may keep with each delivery.

MAX_WEBHOOK_HEADER_NAME_LEN

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.

MAX_WEBHOOK_SIGNATURE_PREFIX_LEN

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