Demo
Demo

Knowledge base

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

http-webhook-ca-file

<acct-file>

A file of trusted authorities for verifying the receiver's certificate
in the configuration this is a linehttp-webhook-ca-fileinside the block <acct-file>
Whom the node trusts at the other end

A PEM file with certificate authority certificates. The node uses them to verify the certificate presented by the receiver. There is no default — without the line, verification uses the operating system’s authority store.

The line is needed in two cases. First: the receiver presents a certificate from its own internal authority, which is not in the system store. Second, the opposite: trust has to be narrowed to one specific authority, so that a certificate from any public one does not pass.

This is about the receiver, not the node. The node presents its own certificate with the http-webhook-certificate line; this one is about whom to trust.

The main trap is setting the file and forgetting about it when the receiver changes. A new receiver with a certificate from a different authority will fail verification, and the symptom will be the familiar one: intermediate files pile up. By default the cause is given away only by a brief error entry in the log; details come with http-webhook-log-verbose.
What the Hub does. It does not write it: the Hub’s certificate is from a public authority, and verification against the system store passes.

The line will be needed if the Hub is deployed inside a perimeter with its own certificate authority — then the nodes will have to be given its certificate with this line.

Recommended values

The default is fine as long as the receiver has a public certificate:

Value When
not set the receiver’s certificate is from a public authority
path to PEM the receiver has its own authority, or trust has to be narrowed
The PEM format and the purpose come from the manual (§ 3.3.11.20). Both reasons to set the line and the warning about changing the receiver are ours.
Example configuration
# the Hub inside the perimeter, certificate from its own authority
<acct-file /var/log/pmta/webhook.json>
    http-webhook-url https://hub.internal/api/telemetry/pmta/7
    http-webhook-ca-file /etc/pmta/internal-ca.pem</acct-file>
When the receiver changes, this line has to be remembered separately: the new certificate may come from a different authority.
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▶

Narrowing trust and forgetting about it when the receiver changes

our experience

What it costsA new receiver with a certificate from a different authority will fail verification. The symptom is the familiar one — files pile up — and the trust line is the last thing people think of.
How to spot itTelemetry disappeared right after the receiver moved.
How to do it rightCheck the chain with the command above and update the authorities file.

Putting the node's own certificate into the line

our experience

What it costsThe line sets trusted authorities for someone else’s certificate. The node presents its own with the http-webhook-certificate line.
How to spot itThe line is set, and the receiver still does not accept the node.
How to do it rightYour own certificate — into http-webhook-certificate, other parties’ authorities — here.
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-ca-file <path>
Values
path to a PEM file with authority certificates
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
No inheritance: the line lives inside its own <acct-file> and concerns verification of only its receiver. Different accounting streams may trust different authorities.
⇄

Related directives

1 relation

Applies to

http-webhook-url<acct-file>The certificate of that address is verified against these authorities. § 3.3.11.20

Referenced from

http-webhook-certificate<acct-file>One line proves the node to the receiver, the other lets the node verify the receiver. § 3.3.11.20

How to check on the node
We check the receiver’s chain with exactly the file we set:
openssl s_client -connect HOST:443 -CAfile /etc/pmta/internal-ca.pem -brief </dev/null
The absence of a Verification error line means the chain matched and the file fits. A verification error means the node will refuse to send the batch.
◇

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
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-extra-headershttp-webhook-max-connectionshttp-webhook-certificateAll 26 directives of the block →