Webhook Registry and Persistence
TheWebhookRegistry manages the persistence of webhook configurations in a TOML-backed store. It ensures that all webhook metadata—including allowed events, sources, and security requirements—is stored securely with owner-only file permissions.
Registry Configuration
The registry is stored in a file namedwebhooks.toml within the daemon’s state directory crates/palyra-daemon/src/webhooks.rs#16-16. It supports up to 1,024 unique integrations crates/palyra-daemon/src/webhooks.rs#17-17.
| Field | Constraint | Description |
|---|---|---|
integration_id | Max 64 bytes | Unique identifier for the integration. |
provider | Max 64 bytes | The source system (e.g., GitHub, Stripe). |
max_payload_bytes | Max 1 MiB | Hard limit on the size of incoming JSON. |
signature_required | Boolean | Whether to enforce HMAC/Signature headers. |
Webhook Readiness State
An integration is considered “Ready” only if it is enabled, has a valid secret reference in theVault, and has no configuration issues crates/palyra-daemon/src/webhooks.rs#81-86.
Ingestion Flow and Security
The daemon handles webhook ingestion through a specialized pipeline that prioritizes security and replay protection.Data Flow Diagram: Webhook Ingestion
The following diagram bridges the natural language flow to the internal code entities. Sources: crates/palyra-daemon/src/webhooks.rs#107-111, crates/palyra-daemon/src/webhooks.rs#218-223, crates/palyra-common/src/process_runner_input.rs#26-31Signature Verification and Replay Protection
Webhooks are verified using thepalyra_common::parse_webhook_payload utility crates/palyra-daemon/src/webhooks.rs#9-9.
- Signature Enforcement: If
signature_requiredis true, the system validates the payload against the secret stored in theVaultcrates/palyra-daemon/src/webhooks.rs#62-62. - Fuzzing: The robustness of the parser is maintained via the
webhook_payload_parserandwebhook_replay_verifierfuzz targets fuzz/Cargo.toml#33-38, fuzz/Cargo.toml#75-79.
CLI Management
Thepalyra CLI provides a comprehensive suite of commands for managing webhooks under the webhooks subcommand crates/palyra-cli/src/commands/webhooks.rs#12-12.
Key Commands
- List:
palyra webhooks listcallscontext.client.list_webhooksto retrieve all configured integrations crates/palyra-cli/src/commands/webhooks.rs#21-31. - Add:
palyra webhooks addcreates a newWebhookIntegrationUpsertRequestcrates/palyra-cli/src/commands/webhooks.rs#36-63. - Test:
palyra webhooks testallows operators to simulate an ingestion using a local file or stdin crates/palyra-cli/src/commands/webhooks.rs#100-131.
Testing Interface
TheTest command is particularly useful for debugging signature issues. It encodes the local payload as Base64 and sends it to the daemon’s test endpoint crates/palyra-cli/src/commands/webhooks.rs#106-110.
Sources: crates/palyra-cli/src/commands/webhooks.rs#100-110, crates/palyra-daemon/src/webhooks.rs#46-49
Error Handling
The system uses a specializedWebhookRegistryError enum to handle various failure modes crates/palyra-daemon/src/webhooks.rs#142-175.
| Error Variant | Cause |
|---|---|
LockPoisoned | Internal mutex failure crates/palyra-daemon/src/webhooks.rs#144-144. |
IntegrationNotFound | Requested integration_id does not exist crates/palyra-daemon/src/webhooks.rs#168-168. |
RegistryLimitExceeded | Attempting to exceed 1,024 integrations crates/palyra-daemon/src/webhooks.rs#172-172. |
InvalidField | Validation failure for identifiers or providers crates/palyra-daemon/src/webhooks.rs#169-170. |