> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/integrations/actions/template/inbound.md).

# inbound

Field reference for the inbound section of an action's YAML definition.

{% hint style="info" %}
This page is the field-by-field reference for the `inbound` section of an action's YAML definition. It is for customizing an action beyond its form. Start with [Actions → The 'inbound' section](https://docs.ilert.com/integrations/actions.md#the-inbound-section) for what the section does and how to edit it.
{% endhint %}

The `inbound` section of an action definition: how callbacks the target system sends to the action's Callback URL are read. Unknown keys are rejected everywhere in this section. ITL and ICL here are evaluated against the inbound context (`payload`, `config`, `vendor`, `map`, `last` and each hydrate id), not the outbound one.

Strings marked ITL are rendered with the ilert template language, strings marked ICL are conditions in the ilert condition language. The variables they can read are described under [Context schema](https://docs.ilert.com/integrations/actions/context.md).

```yaml
openapi: 3.1.0
info:
  title: ilert action template - inbound
  version: 1.0.0
  description: >-
    The `inbound` section of an action definition: how callbacks the target
    system sends to the action's Callback URL are read. Unknown keys are
    rejected everywhere in this section. ITL and ICL here are evaluated
    against the inbound context (`payload`, `config`, `vendor`, `map`, `last`
    and each hydrate id), not the outbound one.
components:
  schemas:
    Inbound:
      type: object
      additionalProperties: false
      properties:
        hydrate:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/HydrateRead'
          description: >-
            Read-only lookups, run in order, for data the callback does not
            carry. Each response becomes a root named after its `id`. Leave
            empty when the callback already carries everything.
        matchBy:
          $ref: '#/components/schemas/MatchBy'
        echoBy:
          type: string
          description: >-
            ITL. Id of the sub-object the callback is about. If a step recorded
            it as `authoredId`, the callback is an echo of ilert's own write
            and is dropped.
          examples:
            - "{{ payload.comment.id }}"
        classify:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/ClassifyRule'
          description: >-
            Ordered rules; the first match wins. A rule without `when` is the
            default and must be last.
        fields:
          type: object
          default: {}
          additionalProperties:
            type: string
          description: >-
            Name to ITL value, extracted for the chosen verb, for example
            `comment` for `COMMENT`. Blank results are dropped. `rePage`
            ("true"/"false") becomes a boolean and `targets` (JSON array text)
            becomes an array.
          examples:
            - comment: "{{ payload.comment.body }}"
        actor:
          $ref: '#/components/schemas/ActorSpec'

    HydrateRead:
      type: object
      additionalProperties: false
      required: [id, url]
      properties:
        id:
          type: string
          minLength: 1
          description: >-
            Root name the response is bound to. Must be unique and must not be
            an inbound root (`payload`, `config`, `last`, `map`, `vendor`).
        method:
          type: string
          enum: [GET, HEAD]
          default: GET
        url:
          type: string
          description: >-
            ITL. May start with `{{ credential.hostUrl }}`. May read only roots
            bound before this read.
        headers:
          type: object
          default: {}
          additionalProperties:
            type: string
        expect:
          $ref: '#/components/schemas/ReadExpect'

    ReadExpect:
      type: object
      description: >-
        Only `successStatus` applies to reads. `condition` is parsed but
        rejected by validation.
      properties:
        successStatus:
          type: array
          default: []
          items:
            type: integer
            minimum: 100
            maximum: 599
          description: Status codes that count as success. Empty means any 2xx.

    MatchBy:
      type: object
      additionalProperties: false
      required: [externalSystem, externalId]
      description: Finds the alert or incident whose twin has this external id.
      properties:
        externalSystem:
          type: string
          description: Must equal the template's brand, for example `jira`.
          examples: [jira]
        externalId:
          type: string
          description: ITL. The object's id as written by `referenceWrite.externalId`.
          examples:
            - "{{ payload.issue.id }}"

    ClassifyRule:
      type: object
      additionalProperties: false
      required: [then]
      properties:
        when:
          type: string
          description: ICL. Absent or blank makes this the default rule.
          examples:
            - "payload.webhookEvent == 'comment_created'"
        then:
          $ref: '#/components/schemas/InboundVerb'

    InboundVerb:
      type: string
      enum: [ACCEPT, RESOLVE, REROUTE, COMMENT, DROP, CREATE]
      description: >-
        What the callback does in ilert. `CREATE` is accepted but not applied
        yet: a callback classified as `CREATE` is dropped.

    ActorSpec:
      type: object
      additionalProperties: false
      properties:
        enrich:
          $ref: '#/components/schemas/ActorEnrich'

    ActorEnrich:
      type: object
      additionalProperties: false
      required: [url]
      description: >-
        A final read that identifies who made the change in the target system,
        so ilert can attribute it to an ilert user.
      properties:
        id:
          type: string
          default: actorLookup
          description: Root name of the response; must not collide with a hydrate id.
        method:
          type: string
          enum: [GET, HEAD]
          default: GET
        url:
          type: string
          description: ITL. May start with `{{ credential.hostUrl }}`.
        headers:
          type: object
          default: {}
          additionalProperties:
            type: string
        expect:
          $ref: '#/components/schemas/ReadExpect'
        map:
          type: object
          default: {}
          description: ITL values rendered with the lookup response bound under `id`.
          properties:
            userId:
              type: string
            email:
              type: string
            origin:
              type: string
          additionalProperties:
            type: string
```


---

# 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.ilert.com/integrations/actions/template/inbound.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.
