> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/triggers-and-webhooks/incoming-webhook-payloads-and-input-mapping.md).

# 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](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FlaLS9Tb4n8wK15mSbV5v%2Fincoming-webhook-payloads-and-input-mapping.png?alt=media)

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.

<details>

<summary>Copy the example</summary>

```json
{
  "event_id": "<stable-sender-event-id>",
  "record": {
    "id": "<external-record-id>",
    "status": "ready_for_review"
  }
}
```

</details>

## 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.

## Related resources

[Trigger Activation and Execution Context](https://docs.stackai.com/technical-reference/triggers-and-webhooks/trigger-activation-and-execution-context.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/triggers-and-webhooks/incoming-webhook-payloads-and-input-mapping.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
