Webhooks

​

Setting up a webhook

​

In the app

​

Via the API

curl -X POST https://api.meetcampfire.com/integrations/api/v1/webhook \
  -H "Authorization: Token $CAMPFIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/campfire/webhook",
    "active": true,
    "topics": [
      {"name": "Invoice.paid"},
      {"name": "Bill.created"}
    ]
  }'

{
  "id": 12,
  "uuid": "3c88df19-1c1f-4b1c-b4a7-768793055a60",
  "url": "https://example.com/campfire/webhook",
  "token": "your-50-character-signing-secret",
  "topics": [
    {"id": 5, "name": "Invoice.paid"},
    {"id": 18, "name": "Bill.created"}
  ],
  "active": true,
  "created_at": "2026-08-04T12:00:00+0000",
  "last_modified_at": "2026-08-04T12:00:00+0000"
}

​

Topics

• Invoice.payment / Bill.payment fires whenever the amount paid increases — including partial payments.
• Invoice.paid / Bill.paid fires when the document transitions to fully paid. When that happens, both the .paid and .payment topics fire (as two separate deliveries), and no .updated event is sent for that change.

​

Payload

{
  "webhook_uuid": "3c88df19-1c1f-4b1c-b4a7-768793055a60",
  "topic": "Invoice.paid",
  "data": {
    "id": 12345,
    "invoice_number": "INV-1042",
    "payment_status": "paid",
    "amount_paid": 1500.0
    // ...full invoice object, same shape as the Invoices API
  },
  "changes": {
    "payment_status": {"old": "open", "new": "paid"},
    "amount_paid": {"old": 500.0, "new": 1500.0}
  }
}

​

Request headers

​

Verifying the signature

{timestamp}:{raw request body}

1. Read the Campfire-Webhook-Request-Timestamp and Campfire-Webhook-Signature-v1 headers and the raw request body.
2. Reject the delivery if the timestamp is too old — we recommend a tolerance of 5 minutes. This protects against replay attacks. (Retried deliveries are re-signed with a fresh timestamp, so a tolerance check will not reject legitimate retries.)
3. Compute HMAC-SHA256 over "{timestamp}:{raw body}" using your signing secret, hex-encode it, and compare it to the signature header using a constant-time comparison.

import hashlib
import hmac
import time


def verify_campfire_signature(raw_body: bytes, headers: dict, secret: str, tolerance_seconds: int = 300) -> bool:
    timestamp = headers["Campfire-Webhook-Request-Timestamp"]
    signature = headers["Campfire-Webhook-Signature-v1"]

    if abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False

    signed_payload = f"{timestamp}:".encode() + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require("crypto");

function verifyCampfireSignature(rawBody, headers, secret, toleranceSeconds = 300) {
  const timestamp = headers["campfire-webhook-request-timestamp"];
  const signature = headers["campfire-webhook-signature-v1"];

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}:${rawBody}`)
    .digest("hex");

  return (
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  );
}

​

Delivery and retries

• Deliveries are POST requests. Respond with a 2xx status code to acknowledge receipt. Any 4xx or 5xx response is treated as a failure.
• Failed deliveries are retried up to 5 times, roughly one minute apart. A 404 response is not retried.
• Each retry is re-signed with a fresh timestamp and signature.
• Respond quickly — acknowledge the delivery first and process the event asynchronously if your handling is slow.
• Deliveries are not guaranteed to arrive in order, and retries mean your endpoint may occasionally receive the same event more than once. Make your handler idempotent — for example, treat the payload’s data as the latest state of the object rather than applying changes incrementally.

​

Delivery logs

curl https://api.meetcampfire.com/integrations/api/v1/webhook/12/events \
  -H "Authorization: Token $CAMPFIRE_API_KEY"

​

Managing webhooks via the API

• {id} is the integer id field from the webhook object, not its uuid.
• url and active are required on create and update.
• topics is a list of {"name": "<topic>"} objects. Topic names must match the values in the topics table exactly.
• Updating topics replaces the full set — include every topic the webhook should be subscribed to, not just new ones.
• token (the signing secret) is read-only and returned on every read. To rotate it, delete the webhook and create a new one.
• To pause deliveries without deleting the webhook, set "active": false.