Header Mapping

Header mapping lets you translate between external message headers and Ditto protocol headers, enabling correlation IDs, content types, and custom metadata to flow through Ditto.

Overview

When Ditto receives messages from or sends messages to external systems, you can map headers between the external protocol and the Ditto protocol. This allows you to:

• Pass headers through Ditto (for example, correlation IDs)
• Map protocol-specific headers to Ditto headers
• Set custom external headers on outgoing messages

You define header mappings individually for each source and target. For configuration examples, see source header mapping and target header mapping.

How it works

A header mapping is a JSON object where:

• Keys are the target header names
• Values are strings that can include placeholders

For inbound messages (sources), the mapping translates external headers to Ditto protocol headers. For outbound messages (targets), the mapping translates Ditto protocol headers to external headers.

If a placeholder fails to resolve, that header is skipped. Other headers and the message itself are still processed.

Configuration

Source header mapping example

{
  "addresses": ["telemetry"],
  "authorizationContext": ["ditto:inbound-auth-subject"],
  "headerMapping": {
    "correlation-id": "{{ header:message-id }}",
    "content-type": "{{ header:content-type }}",
    "device-id": "{{ header:device_id }}"
  }
}

Target header mapping example

{
  "address": "events/twin",
  "topics": ["_/_/things/twin/events"],
  "authorizationContext": ["ditto:outbound-auth-subject"],
  "headerMapping": {
    "message-id": "{{ header:correlation-id }}",
    "content-type": "{{ header:content-type }}",
    "subject": "{{ topic:subject }}",
    "reply-to": "all-replies"
  }
}

Supported placeholders

The supported placeholders for header mapping are defined in the Placeholders - Scope: Connections section.

Special header mapping keys

Ditto recognizes several special header keys that control connectivity behavior.

Response diversion headers

These headers control response diversion:

{
  "headerMapping": {
    "divert-response-to-connection": "webhook-connection",
    "divert-expected-response-types": "response,error",
    "device-id": "{{ header:device_id }}"
  }
}

Protocol-specific headers

Different protocols support different header capabilities:

• AMQP 1.0 – full application properties and message annotations
• MQTT 5 – user-defined properties
• MQTT 3.1.1 – no application headers (only special mqtt.* headers)
• HTTP – standard HTTP headers plus http.query and http.path
• Kafka – Kafka record headers

Further reading

• Connections overview – source and target header mapping configuration
• Placeholders – placeholder syntax and available placeholders
• Response diversion – redirect responses to other connections