Webhook Lifecycle and Data Flow
Webhooks are managed via aWebhookRegistry which persists configuration in a local webhooks.toml file. When an external request arrives, it is validated against an WebhookEnvelope schema, verified for authenticity, and then dispatched to the appropriate internal handler.
Processing Pipeline
- Ingress: The HTTP handler receives a raw byte payload.
- Envelope Parsing: The payload is parsed into a
WebhookEnvelopecrates/palyra-common/src/webhook.rs#26-29. - Signature Verification: The
WebhookSignatureVerifieruses a secret retrieved from theVaultto verify the HMAC or digital signature crates/palyra-common/src/webhook.rs#27-28. - Replay Protection: The
ReplayNonceStorechecks the unique nonce and timestamp to prevent replay attacks crates/palyra-common/src/webhook.rs#27-27. - Payload Extraction: If valid, the inner payload is extracted for domain-specific processing crates/palyra-common/src/webhook.rs#26-26.
Webhook Data Flow Diagram
The following diagram illustrates the flow from an external HTTP request to internal processing. Title: Webhook Ingress and Validation Flow Sources: crates/palyra-daemon/src/webhooks.rs#177-187, crates/palyra-common/src/webhook.rs#26-29, crates/palyra-daemon/src/webhooks.rs#52-72Core Entities and Implementation
WebhookEnvelope
TheWebhookEnvelope represents the standard structure for all incoming webhook requests. It enforces versioning via the v field, typically set to CANONICAL_JSON_ENVELOPE_VERSION (currently 1).
- File:
crates/palyra-common/src/webhook.rs - Version Const:
CANONICAL_JSON_ENVELOPE_VERSION = 1crates/palyra-common/src/lib.rs#32-32
WebhookRegistry
TheWebhookRegistry handles the persistence and lookup of webhook integrations. It limits the total number of integrations to 1,024 to prevent resource exhaustion crates/palyra-daemon/src/webhooks.rs#17-17.
| Constant | Value | Description |
|---|---|---|
MAX_WEBHOOK_COUNT | 1,024 | Max integrations in webhooks.toml crates/palyra-daemon/src/webhooks.rs#17-17 |
MAX_WEBHOOK_PAYLOAD_BYTES | 1,048,576 | Hard limit for any webhook payload (1MB) crates/palyra-daemon/src/webhooks.rs#24-24 |
DEFAULT_MAX_PAYLOAD_BYTES | 65,536 | Default limit (64KB) crates/palyra-daemon/src/webhooks.rs#23-23 |
Security: ReplayNonceStore
To prevent attackers from capturing a valid webhook and re-sending it, Palyra implementsReplayProtection. The ReplayNonceStore tracks nonces within a specific time window. If a nonce is seen twice or the timestamp is too old/too far in the future, the request is rejected.
Sources: crates/palyra-common/src/webhook.rs#27-27
CLI Webhooks Commands
Thepalyra CLI provides a complete suite of commands for managing webhooks, located in crates/palyra-cli/src/commands/webhooks.rs.
| Command | Function | Key Arguments |
|---|---|---|
list | Lists all configured webhooks | --provider, --enabled |
add | Creates a new integration | --integration-id, --secret-vault-ref, --require-signature |
test | Simulates an incoming payload | --payload-file, --payload-stdin |
remove | Deletes an integration | --integration-id |
enable/disable | Toggles active state | --integration-id |
CLI to Daemon Communication
The CLI interacts with the daemon’s Admin API. For example, thetest command encodes the payload as Base64 before sending it to the test_webhook endpoint crates/palyra-cli/src/commands/webhooks.rs#100-110.
Title: Webhook Management Logic Mapping
Sources: crates/palyra-cli/src/commands/webhooks.rs#12-15, crates/palyra-cli/src/commands/webhooks.rs#36-63, crates/palyra-cli/src/commands/webhooks.rs#100-110
JSON Schema (webhook-envelope.v1.json)
The system enforces a strict JSON schema for theWebhookEnvelope. Key requirements include:
v: Must be1crates/palyra-common/src/lib.rs#32-32.integration_id: Must match a configured ID in the registry.signature: Required ifsignature_requiredis true in the record crates/palyra-daemon/src/webhooks.rs#41-41.nonce: Required for replay protection.