For the complete documentation index, see llms.txt. This page is also available as Markdown.

Incoming Webhook Payloads and Input Mapping

An incoming webhook starts work from an HTTP request sent by another system. Map the received payload to the inputs the workflow expects.

Map the sender’s fields to workflow inputs

Illustrative sender payload. Map the actual record.id and record.status body fields to the intended workflow inputs. These are example business fields, not required StackAI webhook fields. Inspect a received event to confirm its shape.

Copy the example
{
  "event_id": "<stable-sender-event-id>",
  "record": {
    "id": "<external-record-id>",
    "status": "ready_for_review"
  }
}

Before you begin

An enabled webhook trigger and access to configure the sending system.

Key concepts

Term
Definition

Webhook

An HTTP request sent by one system to notify another about an event. Delivery and workflow completion are separate outcomes.

Event payload

The data delivered by an event source. Map its actual fields and types to the receiving workflow inputs.

Request body

The payload transmitted with an HTTP request. Interpret it using the content type expected by the endpoint.

Header

A named value sent as HTTP request or response metadata. Authentication and signatures belong in the headers specified by the contract.

Query parameter

A named value carried in a URL’s query string. It is distinct from a similarly named body field; avoid putting secrets there.

Map an incoming webhook payload

  1. Copy the webhook URL from the trigger settings.

  2. Configure the sender’s method, content type, and payload. Map the required body, header, or query values in the workflow.

  3. Send an event and inspect the trigger input and downstream result.

The workflow receives the event fields in the expected types.

Behavior and limitations

JSON, form, and text payloads have different shapes. A field inside the request body is different from a query parameter or header with the same name. Avoid placing credentials in query strings. A successful delivery response does not by itself confirm the entire workflow completed.

Trigger Activation and Execution Context

Was this helpful?