Webhook Destination Config Reference

Webhook sends each event, unmodified, to an endpoint you own. For request mapping, authentication modes, or batching, use HTTP Webhook instead.

In a Webhook destination spec:

• type: webhook
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: events-webhook-prod
spec:
  id: events-webhook-prod
  display_name: Events Webhook Production
  type: webhook
  definition_version: 1
  enabled: true
  config:
    webhook_url: https://hooks.example.com/rudderstack
    webhook_method: POST
    headers:
      - from: X-Signing-Key
        to: "{{ .WEBHOOK_SIGNING_KEY }}"
      - from: X-Environment
        to: "{{ .WEBHOOK_ENVIRONMENT }}"

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

The above example sets two custom headers, and supplies both values through variables because every header value is a secret — see Headers.

Config keys

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

Endpoint

Headers

In this destination, from is the header name and to is its value. That’s the reverse of HTTP Webhook’s headers, where to is the name.

Swapping them doesn’t fail validation — it sends a header named after your value.

headers:
  - from: X-Signing-Key
    to: "{{ .WEBHOOK_SIGNING_KEY }}"

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

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.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers 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. Every type an event stream source can resolve to is supported here, so this check always passes.

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 'events-webhook-prod' config has no 'connection_mode' entry for source type 'web'

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

Secrets

Every headers entry’s to value — the header value — is secret. Write each as a {{ .VAR }} reference and supply the value at apply time:

config:
  headers:
    - from: X-Signing-Key
      to: "{{ .WEBHOOK_SIGNING_KEY }}"

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

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

Note that:

• Header values are masked as a group, so even a constant like application/json is treated as a secret.
• rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.
• Header names (from) aren’t secret and are imported as-is.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

For changes across every destination type, see Destination Type Changes by Release.

See more

• Webhook Destination for dynamic headers, dynamic paths, and transformation examples
• HTTP Webhook Destination Config Reference for the destination with request mapping and authentication modes
• Destination Type Reference for Rudder CLI for the rules shared across destination types