How webhook triggers work

What a webhook trigger is

A webhook trigger is a unique URL that TaskJuice mints for one workflow. When an external system sends an HTTP request to that URL, the workflow runs. There is no polling, no schedule, no intermediate queue — the request arrives, TaskJuice validates it, and the workflow starts.

Each webhook trigger belongs to exactly one workflow. The URL contains a 36-character UUID v4 token that is the only credential proving a request can reach your workflow, so you treat it like a password.

When to use a webhook trigger

Webhooks are the right choice when the external system can call you and you want the workflow to run as soon as the event happens. The classic use cases:

• Provider events — Stripe payment events, GitHub repository events, Linear issue events, Slack message events
• First-party events from your own services — your application notifying TaskJuice when something interesting happens
• Form submissions — direct POSTs from your marketing site or signup form
• IoT devices and edge software — anything that can send an HTTP POST when a sensor reading changes

A webhook trigger is the wrong choice when:

• The external system cannot make outbound HTTP calls. In that case, use a polling trigger so TaskJuice asks the source on a schedule instead.
• The event happens on a fixed schedule. Use a schedule trigger and write the time-based logic directly.
• You need to consume from a message queue (SQS, SNS, Kafka). Use a message queue trigger.
• Multiple tenants share one provider URL (the typical OAuth-app pattern). That requires an app-scoped webhook, which is a separate trigger kind documented elsewhere.

The request lifecycle

When an HTTP request reaches your webhook URL, TaskJuice runs it through a fixed sequence of checks before any workflow code executes. Each check happens in this order, and failing any of them returns an error immediately without proceeding to the next one.

1. Resolve the trigger

   TaskJuice looks up the URL token to find which trigger and workflow it belongs to. Unknown tokens return 404 not found.

2. Validate the HTTP method

   Only GET and POST are accepted. Anything else returns 405 method not allowed with an Allow header.

3. Validate the content type

   For requests with a body, TaskJuice checks the Content-Type header against the configured allowlist. Mismatches return 415 unsupported media type.

4. Validate the request size

   The body is measured against the configured size limit. Oversized payloads return 413 payload too large before any parsing happens.

5. Authenticate the request

   If the trigger has an authentication mode configured, TaskJuice verifies the bearer token, custom header, or HMAC signature. Failures return 401 authentication failed.

6. Parse and normalize the body

   TaskJuice parses the JSON body and normalizes it into an object so your workflow expressions can always assume $trigger is an object. Top-level arrays wrap as { items: [...] }; primitives wrap as { value: ... }.

7. Apply deduplication

   If you have configured a deduplication strategy, TaskJuice computes the dedup key and checks for duplicates within the configured window. Duplicates return 409 duplicate request.

8. Apply the pre-execution filter

   If you have configured a filter, TaskJuice evaluates the expression against the body. Filtered events return 200 received but no workflow run is created.

9. Apply PII redaction

   If you have configured PII redaction, matching field values are replaced with redaction markers before the body reaches your workflow.

10. Dispatch the workflow run

    TaskJuice creates the workflow run, hands the normalized body to your trigger node as $trigger, and returns 200 received to the caller.

The early-rejection ordering matters: cheap checks (URL lookup, method, content type, size) run before expensive ones (authentication, parsing, dedup) so a flood of bad requests cannot cost you compute on the things that take real work.

What you control vs what TaskJuice handles

You configure the trigger from the workflow editor. TaskJuice handles everything between the HTTP request arriving and the workflow run starting.

You never write code for any of the validation, authentication, or normalization steps. They are part of the platform.

How payloads reach your workflow

The body of every accepted request is exposed to your workflow as the expression alias $trigger. The body is normalized into an object before it reaches $trigger so downstream nodes can always assume a consistent shape.

HTTP headers from the incoming request are used internally for authentication and (optionally) deduplication, but they are not included in $trigger. If you need a value the upstream system only sends in a header, ask the upstream system to put it in the body.

Where to go next