Webhooks: Notify external systems on record changes

​

Prerequisites

• An HTTPS endpoint you can deploy code to. It must be publicly reachable from DualEntry’s egress and terminate TLS. Loopback and private IPs are rejected on registration for SSRF protection. If your infrastructure allowlists inbound traffic, permit DualEntry’s source IPs.
• A DualEntry organization-scoped Public API key with the INTEGRATION permission (create, view, edit, archive as appropriate). Create the key under Organization Management → your organization → API Keys. See Authentication.
• A place to store the signing secret returned by the register call. Treat it like a password. It is shown once and can never be retrieved again.
• Agreement with engineering on which topics you need. DualEntry maintains an explicit allowlist of topics for business records (customers, invoices, bills, journal entries, and similar). Not every audited change is exposed.

​

Source IPs to allowlist

​

How DualEntry webhooks work

​

Register a webhook

curl -s -H "X-API-KEY: $KEY" https://api.dualentry.com/public/v2/webhooks/topics/
# -> [{"name": "core.customer/created"}, {"name": "core.invoice/created"}, ...]

curl -s -H "X-API-KEY: $KEY" -H 'Content-Type: application/json' \
  -d '{"url":"https://your-app.example.com/dualentry/webhook",
       "topics":["core.customer/created","core.invoice/created","core.invoice/updated"]}' \
  https://api.dualentry.com/public/v2/webhooks/
# 201 -> {"uuid":"...", "url":"...", "topics":[...], "secret":"whsec_...", ...}

​

Verify and inspect deliveries

• Verify a live delivery. Trigger any subscribed record change (create a customer, edit an invoice) and confirm your endpoint received a POST whose signature verifies against the stored secret. See Verify the HMAC signature below for the algorithm.
• Inspect the delivery log. Every attempt (successful or failed) is recorded. Poll the delivery log by webhook UUID:
  curl -s -H "X-API-KEY: $KEY" \
    https://api.dualentry.com/public/v2/webhooks/<uuid>/deliveries/
  
  Each entry shows event_id, topic, status, attempts, response_status, last_error, delivered_at, and created_at. This is the single source of truth when a downstream system claims it “didn’t get” an event.

​

Payload envelope

{
  "event_id": "b8f4c2a0-1e21-5c9a-bb27-7ac4e6f8b1d2",
  "api_version": "2026-06-27",
  "topic": "core.invoice/created",
  "object_type": "core.Invoice",
  "object": { "id": 4821 },
  "webhook_uuid": "...",
  "created_at": "2026-07-07T14:22:04.123456Z"
}

• event_id is a deterministic UUID. DualEntry generates the same event_id for the same business event across retries, replays, and process restarts, so use it as your idempotency key.
• object is a stable reference ({"id": ...}), not the full record. Fetch the object from the corresponding /public/v2/<resource>/{id}/ endpoint if you need current field values. This keeps the payload compact and avoids shipping stale field snapshots.
• api_version pins the envelope schema for that delivery. Rows in flight during version updates continue to ship with the version they were created under, so key off api_version if you support more than one.

​

Verify the HMAC signature

​

Authentication headers

​

Verification steps

1. Recompute the HMAC over the exact string "<timestamp>.<raw_body>" using your stored secret. Use the raw bytes of the request body. Do not parse JSON and re-serialize, or whitespace and key order will change the hash.
2. Constant-time compare the recomputed digest against the Dualentry-Webhook-Signature-V1 header value. A regular string comparison reveals timing information about prefix matches, enabling timing attacks.
3. Reject stale timestamps. If abs(now - timestamp) > 300 seconds, reject the request. This defeats attackers who capture an old signed request and replay it later.

​

Reference receiver implementation

​

Python / Flask

import hashlib
import hmac
import os
import time
from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["DUALENTRY_WEBHOOK_SECRET"]
seen: set[str] = set()  # replace with Redis / a DB table in production


def is_valid_signature(timestamp: str, body: bytes, signature: str) -> bool:
    """Recompute the HMAC and constant-time compare against the header."""
    signed = f"{timestamp}.".encode() + body
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), signed, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/dualentry/webhook")
def dualentry_webhook():
    body = request.get_data()  # raw bytes - do NOT reserialize
    ts = request.headers.get("Dualentry-Webhook-Request-Timestamp", "")
    sig = request.headers.get("Dualentry-Webhook-Signature-V1", "")

    # 1. Signature check (forged / tampered payloads).
    if not ts or not sig or not is_valid_signature(ts, body, sig):
        return "", 400  # 4xx stops retries

    # 2. Replay window (older than 5 minutes -> reject).
    try:
        if abs(time.time() - int(ts)) > 300:
            return "", 400
    except ValueError:
        return "", 400

    event = request.get_json()

    # 3. Idempotency (at-least-once delivery).
    if event["event_id"] in seen:
        return "", 200
    seen.add(event["event_id"])

    # 4. Dispatch on topic. Return 2xx fast; do heavy work in a queue.
    topic = event["topic"]
    obj_id = event["object"]["id"]
    print(f"received {topic} for id={obj_id}")

    return "", 200

• Signature verification blocks anything that isn’t signed with your secret.
• The 5-minute replay window blocks captured-and-replayed old requests.
• The event_id dedupe handles at-least-once delivery.
• A fast 2xx keeps you out of the retry loop; do the actual work asynchronously.

​

Node.js / Express

// Node.js (Express) - body-parser must expose the raw body.
const crypto = require("crypto");

function isValidSignature(secret, timestamp, rawBody, signature) {
  const signed = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
  const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

​

Manage webhooks over the API

​

Retry, disable, and reactivation policy

curl -s -H "X-API-KEY: $KEY" -H 'Content-Type: application/json' \
  -X PATCH -d '{"is_active": true}' \
  https://api.dualentry.com/public/v2/webhooks/<uuid>/

​

Operate safely in production

​

Troubleshoot common failures

​

FAQ

​

Are webhooks the same as the Stripe / Brex / Plaid webhooks I see in DualEntry?

​

Do webhooks include the full record body?

​

Can I subscribe to every change in the system?

​

Can I use webhooks and polling together?

​

Next steps

• Register your first webhook against a non-production DualEntry organization using the Register endpoint.
• Read the Public API v2 webhooks reference for exact request and response schemas.
• Compare webhook-driven flows to polling in Building a custom integration.
• Return to Integrations for the full list of prebuilt connectors.