Webhooks
Use webhooks when an external system pushes information into Cessy. A webhook should authenticate the sender, validate the payload, and map the payload into a modeled command.
Processing flow
- Receive the external request.
- Verify signature, token, or challenge.
- Validate and normalize the payload.
- Evaluate guard expressions.
- Map payload data into command input.
- Execute the command through the runtime pipeline.
- Record success or failure in Activity and error logs.
Do not let a webhook bypass command validation or permissions.
Signature verification
Configure webhook auth based on the sender’s capabilities. Prefer signed requests. If the sender supports verification challenges, implement the challenge flow before accepting event delivery.
Guard expressions
Use guards to reject irrelevant events early. Keep guards readable and tied to sender payload shape.
Deduplication
If the sender can retry, model idempotency deliberately. The safest approach is often a command that includes the external event id and validates whether it has already been handled.
Error behavior
Webhook errors should be observable:
- invalid auth
- invalid payload
- guard rejected
- mapping failed
- command validation failed
- downstream policy or adapter failed
External senders may retry, so design handlers to be safe under duplicate delivery.