Portal Community
Portal / Nodes / Webhook Trigger / Configuration

Configuration

Configure the Webhook Trigger node to accept the right HTTP requests with proper authentication and response behavior.
Before You Begin When you add a Webhook Trigger node to a workflow, BizFirstAI automatically generates a unique webhook URL for that workflow. You configure the URL path suffix, authentication method, and how the node responds to callers. The generated URL is displayed in the node's detail panel and remains stable across deployments unless you explicitly change the path property.

Properties

Property Type Required Default Description
path String Required Auto-generated The URL path segment appended to the base webhook URL. Can include static segments and named parameters (e.g., /orders/:orderId/confirm). Must start with /. Must be unique within your workspace.
method Enum Required POST The HTTP method the node will accept. One of: GET, POST, PUT, PATCH, DELETE, HEAD. Requests arriving with a non-matching method receive a 405 Method Not Allowed response automatically.
authentication Enum Optional none Authentication scheme applied to incoming requests. Options: none, basicAuth, apiKey, bearerToken. When set to anything other than none, you must also provide the corresponding credential reference.
credential_id Credential Reference Optional None Reference to a stored credential used to validate incoming requests. Required when authentication is not none. Credential must match the selected authentication type (Basic, API Key, or Bearer Token).
response_mode Enum Optional onReceived Controls when the HTTP response is sent back to the caller. onReceived: responds immediately with a 200 status once the webhook is received (fire-and-forget). lastNode: holds the connection open and returns the output of the final node in the workflow as the HTTP response.
response_data Object / Expression Optional {"status": "received"} The data body returned to the caller when response_mode is onReceived. Accepts a static JSON object or a BizFirst expression. Ignored when response_mode is lastNode.
response_status_code Integer Optional 200 HTTP status code returned to the caller. Must be a valid HTTP status code integer (e.g., 200, 201, 202, 400). Only relevant when response_mode is onReceived.
response_headers Object Optional None Additional HTTP headers to include in the response. Provide as a key-value object, e.g., {"X-Workflow-Id": "wf-001", "Content-Type": "application/json"}.
raw_body Boolean Optional false When true, the node passes the raw, unparsed request body as a string instead of attempting JSON or form-data parsing. Useful for receiving XML, plain text, or binary payloads.
max_payload_size Integer (bytes) Optional 1048576 (1 MB) Maximum allowed size of the incoming request body in bytes. Requests exceeding this limit receive a 413 Payload Too Large response. Maximum configurable value is 104857600 (100 MB).

Authentication Options

No Authentication (none)

The webhook URL is accessible to any caller without credentials. Suitable for internal networks or when the calling system uses IP allowlisting instead of credential-based auth. Not recommended for public-facing webhooks.

Basic Authentication (basicAuth)

Requires the caller to supply a username and password in the Authorization: Basic <base64> header. Create a Basic Auth credential in your workspace Credentials store and reference it in credential_id. BizFirstAI validates the credentials on every inbound request before the workflow is started.

API Key (apiKey)

Requires the caller to supply a static API key. You configure whether the key is sent in a header (e.g., X-API-Key) or as a query parameter. The key name and expected value are stored in the referenced credential. This is the most common approach for third-party service integrations like Stripe, SendGrid, and Shopify.

Bearer Token (bearerToken)

Validates a JWT or opaque token in the Authorization: Bearer <token> header. The token value is compared against the secret stored in the credential. For JWT validation, BizFirstAI verifies the signature using the configured public key or secret.

Expression Support

The following properties accept BizFirst expressions (using the {{ }} syntax), allowing you to build dynamic values at runtime:

PropertyExpression SupportNotes
response_data Full expression support Can reference output from prior nodes if response_mode is lastNode. Example: {{ $node["Transform"].output.result }}
response_status_code Expression supported Can be conditionally set, e.g., {{ $input.body.type === "urgent" ? 202 : 200 }}
response_headers Expression supported per value Header values can be expressions; header names must be static strings.
path No expression support Must be a static string. Dynamic values can appear as path parameters (e.g., :orderId) which are captured at runtime.
method No expression support Must be selected from the fixed enum list at design time.
Path Uniqueness The path combined with the method must be unique within your workspace. If two workflows share the same path and method, requests will be routed to the most recently deployed workflow. BizFirstAI will warn you during workflow deployment if a path conflict is detected.
Synchronous vs Asynchronous Use response_mode: lastNode when the calling system needs data back immediately (e.g., returning an order ID or enriched record). Use response_mode: onReceived for long-running workflows where you do not want the caller to wait — respond with a job ID and let them poll or receive a later callback.