INTEGRATION · OUTBOUND WEBHOOKS

Send PostKnock events anywhere

Direct mail usually disappears the moment it leaves the building. Webhooks close that loop: the moment a postcard is delivered, a QR code is scanned, or a follow-up call is logged, PostKnock POSTs a signed JSON payload to a URL you choose. Wire it into your CRM, your on-call channel, or an automation platform, and the rest of your stack finds out at the same time you do.

Set up a webhook

About five minutes, and you never leave the Admin screen.

1. 1

   Open Admin › Webhooks in PostKnock

   Sign in, open Admin, then the Webhooks tab. Select New webhook.

2. 2

   Paste the URL that should receive events

   Any HTTPS endpoint you control. It has to be reachable from the public internet — PostKnock refuses private, loopback and internal addresses, and re-checks that every time it delivers.

3. 3

   Choose the events you care about

   Tick individual events, or subscribe to everything. Most teams start with postcard.delivered and contact.responded — the two that say a mailer is working.

4. 4

   Copy the signing secret

   On save, PostKnock shows a signing secret once. Store it somewhere safe: it is how your endpoint proves a request really came from us, and it is never displayed again. You can rotate it later if it leaks.

5. 5

   Verify the signature on your side

   Every request carries X-PostKnock-Signature: sha256=<hmac>, computed over the raw request body with your secret. Compare it before trusting a payload — sample code is below.

6. 6

   Send a test and watch it land

   Use Test on the webhook to fire a sample event immediately, then open Deliveries to see the status code and response your endpoint returned.

What lands on your endpoint

One POST per event, Content-Type: application/json, sent as PostKnock-Webhook/1.0. Every event uses the same envelope; only data changes shape.

{
  "id": "6f1c9b2e-6c4a-4a1e-9a2f-6c0f4b1d8e77",
  "type": "postcard.delivered",
  "tenant_id": 42,
  "occurred_at": "2026-08-26T14:03:11Z",
  "data": {
    "campaign_id": 7,
    "contact_id": 1183,
    "wave_number": 1,
    "lob_id": "psc_9f2c...",
    "delivered_date": "2026-08-26"
  }
}

Return any 2xx to acknowledge. Anything else — or a timeout — is treated as a failure and retried.

Every event you can subscribe to

Pick the ones you want per webhook, or subscribe to all of them with *. Each event carries the fields listed here inside data.

IDs in data are the same per-account IDs you see in the PostKnock URL bar, so campaign_id: 7 is the campaign at /campaigns/7.

Verifying the signature

Compute an HMAC-SHA256 of the raw request body using your signing secret and compare it to the header. Parse the JSON only after that check passes — and compare in constant time, so a mismatch cannot be probed a byte at a time.

Node.js (Express)

const crypto = require('crypto');

// Give this route the RAW body — JSON.parse first and the bytes you hash
// are no longer the bytes we signed.
app.post('/postknock', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.POSTKNOCK_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  const got = req.get('X-PostKnock-Signature') || '';
  const ok = expected.length === got.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));

  if (!ok) return res.status(401).send('bad signature');

  const event = JSON.parse(req.body);
  // Dedupe on event.id — a retry reuses it, a new event never does.
  console.log(event.type, event.data);
  res.sendStatus(200);
});

Python (Flask)

import hmac, hashlib, os, json
from flask import request, abort

@app.post("/postknock")
def postknock():
    raw = request.get_data()  # raw bytes, before any parsing
    expected = "sha256=" + hmac.new(
        os.environ["POSTKNOCK_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, request.headers.get("X-PostKnock-Signature", "")):
        abort(401)

    event = json.loads(raw)
    # Dedupe on event["id"].
    return "", 200

Connect an automation platform

None of these need a PostKnock-specific app. Each one gives you a URL that accepts a JSON POST; create a Generic webhook in PostKnock and paste it in. From there you can branch on type and push into anything the platform connects to.

Questions