Webhooks and the integrations API

What we send

Every message is one JSON object, version 1:

{
  "id": "evt_3f9a0c...",          // unique per event; the same on every retry
  "type": "visitor.checked_in",
  "version": 1,
  "created_at": "2026-10-09T14:03:11Z",
  "tenant": "your-account",        // your account's short name
  "data": { ... }                  // the fields listed for each event below
}

Headers on every request:

Header	Meaning
X-DFD-Signature	t=<unix seconds>,v1=<hex HMAC-SHA256> — see verifying.
X-DFD-Event-Id	The event's id. Use it to ignore a message you already processed.
X-DFD-Event-Type	The event's type.
X-DFD-Delivery-Id	This delivery, for when you write to us about one.

Privacy by default. We never send a visitor's reason for visiting or their answers to your questions, call transcripts or recordings, the answers to your forms, notes, health details or payment card data. A visitor's name is included only if your arrival alerts may name visitors and you keep visitor details (Kiosk settings → Notifications and Privacy); otherwise visitor_name is null, and your Webhooks settings page says which of the two is keeping it out. Call summaries are sent only to an address you tick "Include call summaries" for. Fields we add later are additive: ignore what you do not recognise.

Events

An event is offered only while the part of the product it comes from is switched on for your account. webhook.test is sent by the "Send test event" button and carries only a message.

Verifying the signature

Each address has its own signing secret (whsec_…), shown once when you add it. The signature is HMAC-SHA256, keyed with the secret, over the timestamp, a full stop, and the exact request body. Reject a message whose signature does not match, or whose timestamp is more than 5 minutes from your clock — that window is what stops somebody replaying a message they captured.

Python

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    fields = dict(part.split("=", 1) for part in header.split(","))
    timestamp = int(fields["t"])
    if abs(time.time() - timestamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields.get("v1", ""))

# Flask:  verify(SECRET, request.headers["X-DFD-Signature"], request.get_data())

Node.js

const crypto = require("crypto");

function verify(secret, header, rawBody, tolerance = 300) {
  const fields = Object.fromEntries(header.split(",").map(p => p.split("=", 2)));
  const timestamp = Number(fields.t);
  if (Math.abs(Date.now() / 1000 - timestamp) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${timestamp}.`).update(rawBody).digest("hex");
  const given = Buffer.from(fields.v1 || "", "hex");
  const want = Buffer.from(expected, "hex");
  return given.length === want.length && crypto.timingSafeEqual(given, want);
}

// Express: app.post("/dfd", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verify(SECRET, req.get("X-DFD-Signature"), req.body)) return res.sendStatus(400);
//   res.sendStatus(200);
// });

Verify against the raw bytes you received, before parsing the JSON — re-serialising changes the bytes and the signature with them.

Delivery and retries

• Answer with any 2xx within 10 seconds. Anything else — including a redirect, which we never follow — counts as a failure.
• A failure is retried up to 8 attempts in all, waiting 1, 2, 4, 8, 16, 32, 64 minutes between them (about 2 hours 7 minutes from the first try to the last).
• Messages can arrive more than once and out of order. Use the event id to ignore repeats, and created_at to order them.
• After 24 failed attempts in a row with nothing delivered for a day, we switch the address off and email the account owner. Switch it back on in Settings once it is fixed; events from while it was off are not resent.
• We only send to public https addresses. Addresses that resolve to a private, loopback or link-local network are refused when you save them and again every time we send.
• The last 30 days of deliveries, with the status code and the start of your reply, are listed under each address in Settings.

The integrations API (Zapier and REST hooks)

Make an API key in Settings, under "Webhooks and Zapier", and send it as X-API-Key: dfd_k_… (or Authorization: Bearer dfd_k_…). A key belongs to one account and is shown once; revoking it also removes every subscription it made.

Call	What it does
GET /api/v1/me	Checks the key; returns your account's name and the events available to it.
POST /api/v1/hooks	Body {"event": "visitor.checked_in", "target_url": "https://…"}. Subscribes the address to one event; returns its id. Messages are the same signed messages described above.
DELETE /api/v1/hooks/{id}	Unsubscribes.
GET /api/v1/hooks	The subscriptions this key made.
GET /api/v1/events/{type}/samples	Up to three recent messages of that event (an example if there are none yet) — what Zapier shows while you build a Zap.

Requests are limited to 60 a minute per address.