Webhook trigger reference

Overview

The webhook trigger fires a workflow whenever an external system sends an HTTP request to a unique URL that TaskJuice mints when you add the trigger to your workflow. This page documents every field you can configure, every response your callers will see, and every limit you need to design around.

If this is your first time building a webhook trigger, start with the quickstart instead — it walks through the minimum setup with a working curl example.

Webhook URL format

When you add a webhook trigger to a workflow, TaskJuice generates a unique URL of this shape:

https://api.taskjuice.ai/webhooks/<endpoint-token>

The endpoint-token is a 36-character UUID v4. It is the only credential that proves a request can reach your workflow, so treat it like a password:

• Never paste it into public chat, screenshots, or version control
• Rotate it (regenerate the trigger) if it leaks
• Restrict where you store it just like you'd restrict an API key

The token is independent of your workflow ID and your subscription ID. Rotating it invalidates the previous URL and breaks any external system still calling the old one.

Allowed HTTP methods

The webhook trigger accepts only GET and POST requests. Every other method returns 405 Method Not Allowed with an Allow header listing the supported methods.

Request body

POST requests can carry a body. TaskJuice parses the body once and exposes it to your workflow as $trigger.

Content type

The Content-Type header is required for POST requests with a body. The default acceptable type is application/json. If you have configured a content-type allowlist (set by the platform team in the trigger definition), requests with any other content type return 415 Unsupported Media Type.

How the body becomes $trigger

TaskJuice normalizes every parsed body into an object before exposing it to your workflow. Three rules apply:

The wrapping is consistent so your downstream nodes can always assume $trigger is an object. If you need to iterate over a top-level array, point a Loop node at $trigger.items.

Authentication modes

You configure authentication on the trigger node from the Authentication Type dropdown. Five modes are supported:

HMAC modes are not available when the trigger only allows GET, because there is no body to sign.

For step-by-step setup of each mode, see the authentication guide.

Replay defense fields (HMAC only)

When you select hmac-sha256 or hmac-sha512, three additional fields appear under the Replay Defense section. All three are optional, and you can set them independently:

A typical Stripe-style configuration uses Timestamp Header = Stripe-Signature-Timestamp, Tolerance = 300, and no nonce header.

Deduplication fields

Deduplication prevents the same logical event from triggering more than one workflow run within a configured time window. You configure it under the Advanced Settings → Deduplication section. The default is Disabled.

Pre-execution filter fields

The pre-execution filter lets you accept the request but skip running the workflow when the body doesn't match a condition. Configure it under Advanced Settings → Pre-Execution Filter.

A filtered request still returns 200, so the upstream system doesn't retry. The filter happens before the workflow run is created, so filtered events do not appear in your run history.

PII redaction fields

PII redaction replaces matching field values in the parsed body with a redaction marker before the workflow runs. Field names are matched against your regex patterns case-insensitively. Configure it under Advanced Settings → PII Redaction.

Redaction applies before the body reaches $trigger, so your workflow expressions never see the original values.

Successful response

When TaskJuice accepts and dispatches a webhook event, it returns a 200 OK with this exact body:

{
  "received": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

The response also carries an X-Request-Id header with the same UUID:

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000

{"received":true,"request_id":"550e8400-e29b-41d4-a716-446655440000"}

The request_id is a per-request correlation token. It identifies a single delivery attempt and is the join key you use to find the corresponding entry in your run history or to reference when contacting support. The same UUID appears in the X-Request-Id header so tools that prefer headers (most observability platforms) pick it up automatically.

When the request is technically valid but produces no workflow run (an empty GET with no query parameters, for example), the response is 200 with this body:

{
  "received": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

The same shape — there is no separate "empty" status leaked to the caller. Your run history shows whether a run was created.

Error responses

Every error response shares the same shape:

{
  "error": "<short generic message>",
  "request_id": "<uuid>"
}

The HTTP status code carries the actual meaning. The body's error field is a short, lowercase, generic phrase chosen from a fixed list. The same string is returned for every reason a given status class can fire — for example, every 401 says "authentication failed" regardless of whether the signature was wrong, the timestamp was expired, or the header was missing. This is intentional: a more specific message would tell an attacker which guess was closer to correct.

For 5xx responses, the body never includes any details about the underlying failure — no exception class names, no stack traces, no service names. The request_id is the only identifier you should report when filing a support ticket.

Using the request_id

The request_id returned in every response is the join key that connects three places:

1. The HTTP response the upstream system received (body field and X-Request-Id header)
2. The run history entry in your TaskJuice dashboard for that delivery attempt
3. The internal logs TaskJuice support uses to investigate failures

When you contact support about a failed delivery, include the request_id exactly as it appeared in the response. Without it, support has to search by approximate timestamp, which is slower and less reliable.

The request_id is generated fresh per request. It does not identify your workflow, your subscription, or your tenant — only the specific HTTP attempt. Sharing one is safe.

Accessing trigger data in workflow expressions

Inside your workflow, every node downstream of the trigger can read the request body via the $trigger expression alias. The shape of $trigger follows the body normalization rules from the Request body section.

$trigger does not contain headers. If you need a value the upstream system only sends in a header, ask the upstream system to put it in the body.

Limits

Hard limits enforced by the platform. These are not configurable from the workflow editor.

The body size limit is enforced before authentication, so an oversized payload is rejected with 413 without consuming any auth verification work.

Related

• Send your first webhook — set one up in five minutes with curl
• Authenticate your webhook — configure HMAC, bearer, or custom-header auth
• Filter, deduplicate, and redact webhook events — recipes for the advanced settings
• How webhook triggers work — the conceptual model