Demo
Demo

Knowledge base

PMTA knowledge base›Block <acct-file>›Directive§ 3.3.11.18

http-webhook-extra-headers

<acct-file>set by the Hub

A file with extra webhook request headers
in the configuration this is a linehttp-webhook-extra-headersinside the block <acct-file>
The only way to add a header to the request

The engine can add arbitrary headers to a webhook request only from a file — one per line. They cannot be written directly into the configuration.

The main use is authorization. The receiver has to somehow learn that the batch came from the right node, and the Authorization header is where that is customarily written.

The second use is overriding the content type. By default it is derived from the path extension, and if the receiver expects something else, a Content-Type line in this file overrides it.

A separate file is a good thing. The token gets neither into the address nor into the configuration itself: the file has its own permissions, and only the engine reads it.

The main trap is leaving the file with ordinary permissions. It holds the receiver’s secret. The configuration is read and copied, but at least it has a reputation as a file with secrets; the headers file does not, and its permissions are often left as they were at creation.
What the Hub does. It writes it — it puts /etc/pmta/mtahub-headers.txt with a single line Authorization: Bearer <token> and sets permissions to 600. A 48-character token is issued to the node once and stored in nodes.webhook_token_encrypted.

The file name is our own, not a shared one. If the node is later connected to Protosender, its token will sit next to ours rather than over it.

The receiver accepts the token both in the Authorization: Bearer header and in the X-MTAHub-Token header; the comparison is constant-time, and the response to a wrong token and to a nonexistent node is identical — there is nothing to guess from differences in responses.

Recommended values

In the file — one header per line:

Header Why
Authorization the receiver recognizes the node
Content-Type to override the one derived from the extension
your own if the receiver requires it

File permissions — 600, owned by the user the engine runs as.

The file format and both uses come from the manual (§ 3.3.11.18). The 600 permissions and the argument that a separate file is better than the address are ours.
Example configuration
# the configuration holds only the path
<acct-file /var/log/pmta/mtahub-webhook.json>
    http-webhook-url https://hub.example.com/api/telemetry/pmta/7
    http-webhook-extra-headers /etc/pmta/mtahub-headers.txt</acct-file>

# the file /etc/pmta/mtahub-headers.txt holds one header per line:
#     Authorization: Bearer d41d8cd98f00b204e9800998ecf8427e
The file contents are shown as a comment: they are not in the configuration and cannot be. Its permissions are 600.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Leaving the headers file with default permissions

our experience

What it costsThe receiver’s secret becomes readable by everyone with access to the node and gets into backups along with ordinary files.
How to spot itls -l shows permissions broader than 600.
How to do it rightchmod 600, owned by the engine’s user.

Writing the headers directly into the configuration

§ 3.3.11.18

What it costsThe directive accepts only a file path. An attempt to write a header as a line achieves nothing, and the request will go out without it — that is, without authorization.
How to spot itThe receiver answers 401 with an entirely correct token in the configuration.
How to do it rightMove the headers into a file and specify the path to it.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
http-webhook-extra-headers <path>
Values
a file path; in the file one HTTP header per line
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<acct-file>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
There is no inheritance: the line lives inside its <acct-file> and applies only to this stream’s requests. Two accounting blocks can have different receivers and different header files.
⇄

Related directives

2 relations

Does not work without

Lock down permissions on configuration filesThe file holds the receiver’s token, so its permissions matter as much as the token itself. § 1.6.3

Applies to

http-webhook-url<acct-file>The headers are added to the very request that carries the batch. § 3.3.11.18

How to check on the node
Check both the permissions and the contents — with one command:
ls -l /etc/pmta/mtahub-headers.txt && head -c 40 /etc/pmta/mtahub-headers.txt
The permissions must be 600. If the receiver answers 401, it is exactly this file that needs checking: the engine sends what is written in it and will not notice an error in a header itself.
◇

What else to read

3 articles

◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.◇Two inbound report processors and what to do with themBounces by message and complaints are parsed by two identically structured blocks; each has its own address list and its own pair of decisions about the message’s fate.◇Five ways for a queue to hand off a messageA queue does not have to use SMTP: it can write to a file, run a program, call over HTTP or discard.

In the Hub
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Collect telemetry
Neighboring settings of the block <acct-file>:http-webhook-urlhttp-webhook-max-intervalhttp-webhook-max-connectionshttp-webhook-connect-timeouthttp-webhook-ca-fileAll 26 directives of the block →