HTTP Webhook Destination Config Reference Beta

HTTP Webhook sends each event to an HTTP endpoint you own. You choose the method, body format, authentication, and — when the default passthrough doesn’t suit the endpoint — how RudderStack maps the event onto the outgoing request.

In an HTTP Webhook destination spec:

• type: http
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: orders-webhook-prod
spec:
  id: orders-webhook-prod
  display_name: Orders Webhook Production
  type: http
  definition_version: 1
  enabled: true
  config:
    api_url: https://api.example.com/v1/events
    method: POST
    format: JSON

    auth: apiKeyAuth
    api_key_name: "{{ .WEBHOOK_API_KEY_NAME }}"
    api_key_value: "{{ .WEBHOOK_API_KEY }}"

    is_default_mapping: false
    properties_mapping:
      - to: $.eventName
        from: $.event
      - to: $.customer.id
        from: $.userId
    query_params:
      - to: source
        from: rudderstack
    headers:
      - to: X-Request-Source
        from: "{{ .WEBHOOK_HEADER_VALUE }}"
    path_params:
      - path: $.properties.accountId

    is_batching_enabled: true
    max_batch_size: "50"

    event_filtering:
      whitelist:
        - Order Completed
        - Order Refunded

    connection_mode:
      web: cloud
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics

The above example uses API key authentication and custom request mapping. xml_root_key is omitted because it applies only when format is XML. Several keys apply only in certain combinations — see Key dependencies.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Key dependencies

Several keys only take effect in combination with another key’s value. The CLI enforces one of these — max_batch_size — and accepts the rest whatever the other key says, so a key that doesn’t apply is stored and ignored rather than rejected.

Endpoint

Authentication

Request mapping

By default the source event is sent through unmodified. The keys in this group either turn that off and reshape the body, or add to the request URL and headers — those additions apply either way.

Each mapping entry pairs a from (where the value comes from) with a to (where it lands on the outgoing request). A from is a JSONPath into the source event, such as $.properties.orderId, or a bare constant such as rudderstack. A quoted constant like "EUR" is not valid.

If you define more than one mapping for the same key, only the first is used and the rest are ignored.

properties_mapping:
  - to: $.messageType
    from: $.type
  - to: $.customer.firstName
    from: $.traits.firstName

query_params:
  - to: source
    from: rudderstack
  - to: order_id
    from: $.properties.orderId

headers:
  - to: X-Request-Source
    from: rudderstack

path_params:
  - path: accounts
  - path: $.properties.accountId

Batching

is_batching_enabled: true
max_batch_size: "50"

Event filtering

event_filtering:
  whitelist:
    - Order Completed
    - Order Refunded

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode:
  web: cloud
  cloud: cloud

Source types

HTTP Webhook accepts events from these source types in the mentioned connection modes:

Every source type is cloud only — events reach the endpoint from RudderStack’s servers, never in device mode.

Unlike most destination types, HTTP Webhook accepts warehouse, the token a Reverse ETL source resolves to.

The dashboard additionally offers HTTP Webhook to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify are invalid here.

Connect a source

An event stream connection to this destination is checked against two rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. An unsupported type reports:

destination 'orders-webhook-prod' (type 'http') does not support source 'my-source':
source type 'amp' is not among supported source types: android, android_kotlin, ...

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'orders-webhook-prod' config has no 'connection_mode' entry for source type 'web'

HTTP Webhook needs no additional config keys to connect a source of any type.

Secrets

Rudder CLI treats six keys as secrets: username, password, bearer_token, api_key_name, api_key_value, and every headers entry’s from value. Write each as a {{ .VAR }} reference and supply the value at apply time:

config:
  auth: apiKeyAuth
  api_key_name: "{{ .WEBHOOK_API_KEY_NAME }}"
  api_key_value: "{{ .WEBHOOK_API_KEY }}"
  headers:
    - to: X-Request-Source
      from: "{{ .WEBHOOK_HEADER_VALUE }}"

export RUDDER_WEBHOOK_API_KEY="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

• api_key_name is the header name, not the key itself, and the dashboard stores it in the clear. Rudder CLI masks it anyway, on the grounds that a custom header name identifies the endpoint’s auth scheme.
• headers values are masked as a group, because a header is a common place to put a signing secret. If you use headers only for constants, they’re still written back as {{ .VAR }} placeholders on import, and you’ll need to fill each one in.
• rudder-cli import writes every one of these keys back as a {{ .VAR }} placeholder rather than its value, since the API doesn’t return secrets. Fill the placeholders in before the first apply.

See How to Use Variable Substitution in Rudder CLI.

See more

• HTTP Webhook Destination for the mapping UI, worked payload examples, and FAQ
• Destination Type Reference for Rudder CLI for the rules shared across destination types
• Destination YAML Reference for the spec envelope