kestra-io / kestra-io/docs

Webhook trigger docs incorrectly claim built-in HMAC signature validation

Open Beginner friendly
#5,345 0 comments 0 reactions 0 assignees View on GitHub
area/docs good first issue kind/customer-request
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.