Demo
Demo

Knowledge base

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

http-webhook-certificate

<acct-file>

The client certificate the node presents to the receiver
in the configuration this is a linehttp-webhook-certificateinside the block <acct-file>
A second way to prove the batch comes from the right node

A PEM file with a client certificate. The node will present it to the receiver if the receiver requests it. There is no default.

This is an alternative to a token in a header. The receiver has to tell its own nodes from others somehow, and there are two ways: a secret in a header (http-webhook-extra-headers) or a certificate. The second is harder to maintain — certificates expire — but it is not sent in every request and does not lie in a file in plain text.

The line requires nothing. If the receiver does not ask for a certificate, it simply will not take effect — and silently: there will be no error, and no authorization either.

The main trap is forgetting about the expiry date. An expired certificate means a refusal from the receiver, a retry and a pile-up of intermediate files — exactly the same symptom as all other webhook faults. On the expiry day telemetry will simply stop arriving.
What the Hub does. It does not write it: nodes identify themselves with a token in a header. A 48-character token is issued at the first configuration apply and stored on our side; it does not expire, and revoking it means rewriting one file on the node.
Recommended values

A choice between two ways of proof:

Method Pro Con
token in a header nothing to expire, revocation — one file the secret goes out in every request
client certificate the secret is not transmitted expires, needs issuing and renewal

Together they are not needed, although they do not interfere with each other.

The PEM format and the condition “if requested” come from the manual (§ 3.3.11.19). The comparison of the two ways of proof and the warning about expiry are ours.
Example configuration
# the receiver requires a client certificate instead of a token
<acct-file /var/log/pmta/webhook.json>
    http-webhook-url https://partner.example.com/ingest
    http-webhook-certificate /etc/pmta/webhook1-client-cert.pem</acct-file>
The certificate’s expiry date is worth keeping in the same list as the expiry dates of mail-receiving certificates: expiry looks like a broken webhook.
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▶

Setting a certificate for a receiver that does not ask for it

our experience

What it costsThe line will not take effect, and there will be no authorization. There is no error either — the receiver simply refuses for its own reason, and it will look like files piling up.
How to spot itThe certificate is set, the receiver replies 401.
How to do it rightCheck whether the receiver requests a certificate; if not, use a token in a header.

Not watching the expiration date

our experience

What it costsOn the expiry day telemetry stops arriving, and the symptom is the same as for all other webhook faults — files pile up.
How to spot itData disappeared on a single day without configuration edits.
How to do it rightKeep the expiry date in the node’s common list of certificate expiry dates.
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-certificate <path>
Values
path to a PEM file with a client certificate
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 applies to connections to only its receiver. Different receivers — different certificates.
⇄

Related directives

2 relations

Works together with

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

Applies to

http-webhook-url<acct-file>The certificate is presented when contacting that address. § 3.3.11.19

How to check on the node
First it is worth finding out whether the receiver asks for a certificate at all:
openssl s_client -connect HOST:443 -msg </dev/null | grep -c CertificateRequest
0 means it does not ask, and the line will not take effect. The expiry date of your own certificate is checked like this: openssl x509 -enddate -noout -in FILE.
◇

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-ca-fileAll 26 directives of the block →