Articles in this section

Use webhook headers and query parameters in a transformation

A webhook request carries information outside its body, in HTTP headers and URL query parameters. A Rules 2.0 transformation on a webhook listener can read these values and write them to fields on each record, so the rest of the flow can act on them. This article shows how to reference webhook headers and query parameters in a transformation, with an example that routes events by type.

When to use webhook request data

  • Process several event types with one listener — The sending application identifies the event type in a header, such as X-Event-Type. Write the event type to the record, and use it to filter or branch the flow instead of building a separate listener for each event type.
  • Route or filter by a query parameter — The request URL includes a value such as ?orderId=12345. Write it to the record so later steps can filter or route on it.

Reference a header or query parameter

  1. Open the Define transformation editor on the webhook listener, and select Rules 2.0. For steps, see Add a transformation to a flow step.
  2. Add an output field for the value, for example eventType.
  3. Select Settings for the field.
  4. In Field transformation type, select Handlebars expression.
  5. Enter the expression for the value, using three braces so handlebars doesn't HTML-escape characters such as = and &:
    • For a header, enter {{{headers.<header name>}}}, for example {{{headers.x-event-type}}}.
    • For a query parameter, enter {{{queryParams.<parameter name>}}}, for example {{{queryParams.orderId}}}.
  6. Preview the transformation, confirm the output field contains the expected value, and then save. For the steps, see Preview and save.

Paths and names are case-sensitive. integrator.io stores webhook header names in lowercase, so enter them in lowercase, for example x-event-type, even if the sending application sends X-Event-Type. Query parameter names keep the case the sender used, so ?Mode=Test is queryParams.Mode.

Example: Route webhook events by type

An application sends order and refund events to the same webhook listener and identifies each event in the X-Event-Type header. You want orders and refunds to follow different paths in the flow.

  1. In the listener's Rules 2.0 transformation, set JSON structure to Modify input record { }, so the event body passes through unchanged.
  2. Add the output field eventType with the handlebars expression {{{headers.x-event-type}}}.
  3. Save the transformation.
  4. After the listener, add branching with one branch for eventType equal to order and another for eventType equal to refund.

Each record now carries its event type, and the branching sends it to the steps for that type.

Data available from a webhook listener

A webhook listener's envelope contains the request's headers and queryParams, along with record, job, settings, and other runtime data. For the full structure and a sample, see Transformation 2.0 input context reference.