Webhook trigger docs incorrectly claim built-in HMAC signature validation
- Dominant language
- Astro
- Stars
- 155
- Forks
- 177
- Avg merge
- 1d 20m
- Merged PRs (30d)
- 192
Description
### Summary
`webhook-security-best-practices/index.md` states twice that Kestra's core `Webhook` trigger has built-in HMAC signature validation. It does not. This is misleading and was reported by a customer (Pylon #2222) who tested it and found any request with a signature header present is accepted, regardless of whether the signature is valid.
### Incorrect claims
**Line 90:**
> For more details on implementation, see how to use a [Webhook Trigger in Kestra](/docs/workflow-components/triggers/webhook-trigger), which has built-in support for signature validation.
**Line 164:**
> **Built-in Validation:** The native `Webhook` trigger can automatically validate HMAC signatures, simplifying the most critical security step.
### Actual behavior
The core `io.kestra.plugin.core.trigger.Webhook` trigger (`kestra` repo, `core/src/main/java/io/kestra/plugin/core/trigger/Webhook.java`) has no HMAC computation, secret-based digest, or signature comparison logic. The only built-in security mechanism is the `key` embedded in the webhook URL path (`.../executions/webhook/{namespace}/{flowId}/{key}`), which acts as a shared secret in the URL — not a payload signature check.
Verified across `WebhookService.newExecution()`, `WebhookValidator`, and `AbstractWebhookTrigger` — none contain HMAC/crypto logic. The reference page `docs/05.workflow-components/07.triggers/03.webhook-trigger` doesn't make this false claim, so it's fine; only this best-practices article is wrong.
Real signature verification in Kestra today is implemented per-integration at the task level by specific plugins wrapping a provider SDK, e.g. `io.kestra.plugin.stripe.webhook.HandleEvent`, which calls `com.stripe.net.Webhook.constructEvent(payload, sigHeader, secret)` as a task *after* the webhook trigger has already created the execution. There is no generic/provider-agnostic HMAC verification capability in core.
### Suggested fix
- Line 90: remove "which has built-in support for signature validation," replace with something like "see how to use a [Webhook Trigger in Kestra](/docs/workflow-components/triggers/webhook-trigger) to expose the endpoint, then validate the signature in a task before acting on the payload."
- Line 164: replace the "Built-in Validation" bullet — it should describe validation as a task-level pattern (e.g. referencing the Stripe plugin, or a shell/openssl HMAC comparison + `runIf`/`Exit` task for providers without a dedicated plugin), not something the trigger does automatically.
- Consider revising the `github-push-receiver` example flow so it doesn't imply the `ExpressionCondition` checking header *presence* is equivalent to signature *verification*.
### Reference
Pylon ticket #2222 (customer issue).
Contributor guide
Research direction
Open webhook-security-best-practices/index.md and review the claims around lines 90 and 164, along with the github-push-receiver example. Compare them with the Webhook trigger reference and the issue’s description of task-level validation. Done means the article no longer implies core HMAC validation and clearly distinguishes endpoint access from signature verification.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100