Inbound Webhooks
The daemon manages a registry of webhook integrations, each defined by a provider, a secret for signature validation, and a set of allowed event types.Webhook Registry and Persistence
Webhook configurations are persisted in a TOML-backed registry managed by theWebhookRegistry struct crates/palyra-daemon/src/webhooks.rs#107-111. The registry is stored at webhooks.toml within the daemon’s state root crates/palyra-daemon/src/webhooks.rs#16.
Key constraints enforced by the registry:
- Max Count: 1,024 integrations crates/palyra-daemon/src/webhooks.rs#17.
- Payload Size: Default limit of 64 KB, configurable up to 1 MB crates/palyra-daemon/src/webhooks.rs#23-24.
- Validation: Identifiers and providers are limited to 64 bytes crates/palyra-daemon/src/webhooks.rs#18-19.
Security and Validation
To prevent unauthorized or malicious payloads, the subsystem implements several security layers:- Signature Validation: If
signature_requiredis enabled for an integration, the daemon validates the inbound request signature using a secret stored in theVaultcrates/palyra-daemon/src/webhooks.rs:41, 62. - Replay Protection: The system checks for duplicate payloads within a configured window fuzz/fuzz_targets/webhook_replay_verifier.rs#1-10.
- Envelope Schema: Inbound JSON must conform to the
webhook-envelope.v1.jsonschema, ensuring consistent parsing of event types and sources.
System Events
System Events are internal triggers emitted by various subsystems (Gateway, Auth, Memory) to record significant actions. These are stored in the Journal Store’sjournal_events table.
Event Emission Flow
Events are emitted via theconsole/v1/system/events/emit endpoint crates/palyra-cli/src/commands/system.rs#41. Each event includes:
- Name: A unique identifier for the event type (e.g.,
connector.registered) crates/palyra-connector-core/src/supervisor.rs#229. - Severity: Info, Warn, or Error crates/palyra-cli/src/args/system.rs#42-46.
- Details: A JSON object containing metadata specific to the event crates/palyra-cli/src/commands/system.rs#45.
Data Flow: System Event Ingestion
The following diagram illustrates how a system event moves from a subsystem like theConnectorSupervisor to the persistent journal.
Title: System Event Propagation
Sources: crates/palyra-connector-core/src/supervisor.rs#227-240, crates/palyra-daemon/src/transport/http/handlers/console/system.rs#159-168
CLI Management
Thepalyra webhooks and palyra system command families provide administrative control over these subsystems.
Webhook Commands
The CLI allows operators to manage the lifecycle of webhook integrations:add: Registers a new provider with a specific secret reference.list: Displays all configured integrations and their readiness status crates/palyra-daemon/src/webhooks.rs#189-216.test: Triggers a validation check for a specific integration crates/palyra-daemon/src/webhooks.rs#46-49.
System Event Commands
Used for auditing and manual event injection:palyra system events list: Fetches recent events with support for filtering bykind,principal, orchannelcrates/palyra-cli/src/commands/system.rs#29-33.palyra system events emit: Manually records a custom event into the system log crates/palyra-cli/src/commands/system.rs#34-54.
Code Entity Association
This diagram maps CLI commands to the underlying Rust functions and API routes. Title: CLI to Daemon Mapping Sources: crates/palyra-cli/src/commands/system.rs#15-56, crates/palyra-daemon/src/webhooks.rs#107-118, crates/palyra-cli/src/args/system.rs#21-39Technical Specifications
Webhook Integration Record
Each entry in theRegistryDocument contains the following fields:
| Field | Type | Description |
|---|---|---|
integration_id | String | Unique identifier (normalized) |
provider | String | Source platform (e.g., “github”, “stripe”) |
secret_vault_ref | String | Reference to palyra-vault for signature keys |
allowed_events | Vec<String> | Filter for permitted event types |
signature_required | bool | Enables cryptographic payload validation |
max_payload_bytes | u64 | Hard cap on inbound POST body size |
Diagnostic Statuses
The system tracks readiness viaWebhookReadiness crates/palyra-daemon/src/webhooks.rs#75-80, which checks:
- Secret Presence: Verifies the
VaultRefresolves to a valid secret crates/palyra-daemon/src/webhooks.rs#89-93. - Configuration: Validates that filters and identifiers meet byte-size constraints.