Extending Campfire with your app

An OAuth app can do more than call the API. It can also put itself inside Campfire:

Buttons on invoice and bill pages that open a link, call your server, or open your page in a drawer.
Panels: your page embedded as a tab on a list page, a detail page, or an edit modal.
Navigation: a section in Campfire’s sidebar with full-width pages from your app.
A manage link from the connection page to your app’s settings screen.
Event subscriptions: signed notifications when records change in any workspace that connected your app.

You define all of this once, on the app. It then shows up in every workspace where someone has connected the app, and each workspace’s admins can switch individual pieces off.

FakeTax sample app

A complete, open-source Flask app that uses every feature on this page. All the screenshots here come from it.

App manifest

Define the whole app, including everything on this page, as one JSON document you keep in your repository.

The sample app: FakeTax

FakeTax puts made-up sales tax on invoices. The tax is fake, but the plumbing is real, so it’s a working reference for each capability:

Capability	What FakeTax does with it
Webhook button	Calculate tax on an invoice reads the invoice, writes tax on every line, and tells Campfire to show a toast and refresh.
Bulk webhook button	Calculate FakeTax on the invoice list does the same for up to 50 selected invoices.
Iframe button	Tax breakdown opens FakeTax in a drawer where you can override the rate and apply it.
Link button	View in FakeTax opens a per-line report in a new tab, after verifying a single-use context token.
Panels	A FakeTax tab on the invoice page and edit modal, and a settings tab on the invoice list.
Navigation	A FakeTax sidebar section with Jurisdictions, Tax codes, and Settings pages.
Manage link	Manage in FakeTax on the connection page opens FakeTax’s settings, signed in.
Events	`Invoice.created` triggers automatic tax calculation when that option is on.
Install config	Per-workspace settings (default rate, auto-calculate) stored in Campfire.

The repository’s README covers local setup. In short: create an app, paste manifest.json into its Manifest tab, rotate the signing secret, put the credentials in .env, and run python app.py.

Before you start

Have extensions turned on

Buttons, panels, navigation and events only appear in, and are only sent to, workspaces that have app extensions turned on. Contact your Campfire support team to turn them on for your workspace and for the workspaces you’re building for. You can define everything on your app before that. It just won’t show.

Add your allowed domains

On your app’s page (Settings > Developer > Apps > Manage), open the Security tab. Every button URL, panel and page URL, and event endpoint must be https on one of these hosts. example.com matches only that host. *.example.com matches its subdomains, but not example.com itself. You can add up to 20. Plain http is accepted only for localhost.

The Security tab with an allowed domain and the signing secret

Rotate the signing secret

Campfire signs every webhook call, event delivery and context token with your app’s signing secret (whsec_...). This is separate from your OAuth client secret. A signing secret is created automatically, but its value is never shown, so click Rotate Secret to get one you can copy. It’s shown once.After a rotation, Campfire signs with both the new and the previous secret for 24 hours, so you can deploy the new secret without dropping requests.

Extensions show only in workspaces where at least one person has connected your app. Your own workspace counts. Other workspaces see them only once your app is published and approved. Disconnecting the last connection in a workspace removes them there.

Buttons

Buttons add actions to Campfire pages. Manage them on your app’s Buttons tab.

On an invoice, FakeTax’s Calculate tax is a secondary button in the page header, and its other buttons are grouped under the app’s name in the Actions menu:

An invoice page with a Calculate tax button and a FakeTax group in the Actions menu containing Tax breakdown and View in FakeTax

Click Add Button, or click an existing button, to edit it:

The Edit Calculate tax sheet with label, key, object, placement, style, action, icon, URL template, timeout, confirmation and visibility rule

Field	Notes
Label	Up to 60 characters.
Key	A stable identifier, unique within the app. Defaults to a slug of the label. Campfire sends it back to you as `slot_key`.
Object	`invoice`, `bill`, `journal_entry`, or `vendor`.
Placement	`detail_header` (the record’s page), `list_header` (the list page, acting on selected rows), or `row_menu` (a list row’s menu).
Style	`menu` (default), `secondary`, or `primary`. See How buttons are styled.
Action	`link`, `webhook` (Call webhook), or `iframe` (Embedded page).
Icon	A Lucide icon name in kebab-case, for example `calculator`.
URL template	Where the action goes. See URL templates.
Confirmation	Optional, up to 200 characters. Campfire asks the person to confirm before running the action.
Show only when	Optional rules that hide the button for records that don’t match. See Visibility rules.

An app can have up to 50 buttons.

Where buttons appear today: the invoice page header, the invoice list header (with rows selected), and the bill page header. You can define buttons for other objects and placements now. They’ll appear as Campfire adds them to more pages.

Link buttons

A link button opens your URL in a new tab, with a signed context token added as cf_ctx:

https://your-app.com/report/18545770?cf_ctx=eyJhbGciOiJIUzI1NiIs...

Verify the token before showing anything. FakeTax’s View in FakeTax opens a report only after the token checks out, and refuses it on reload because the token is single-use:

The FakeTax report for an invoice, opened from Campfire with a context token

Webhook buttons

A webhook button calls your server and shows the result without the person leaving Campfire. Optionally, Campfire asks them to confirm first:

A Calculate tax confirmation dialog asking Overwrite tax on every line?

Campfire then sends a signed POST to your URL:

POST /slots/calculate HTTP/1.1
Content-Type: application/json
Campfire-App-Id: 0ca4c60f-db0a-4bc3-9efa-d2dec4292130
Campfire-Delivery-Kind: slot
Campfire-Webhook-Request-Timestamp: 1791990000
Campfire-Webhook-Signature-v1: 5d1c0e...

{
  "kind": "slot.invoked",
  "slot_key": "calculate",
  "object_type": "invoice",
  "object_ids": ["18545770"],
  "surface": "detail_header",
  "user": {"id": 31017},
  "customer": {"id": 52},
  "context_token": "eyJhbGciOiJIUzI1NiIs..."
}

Check the signature, do the work (usually by calling the Campfire API with the connection’s OAuth token), and reply with up to four effects:

{
  "effects": [
    {"type": "toast", "level": "success", "message": "FakeTax: Tax $174.00 written on 1 invoice"},
    {"type": "refresh"}
  ]
}

Effect	Fields	What Campfire does
`toast`	`level` (`success`, `info`, `warning`, `error`), `message` (up to 200 characters)	Shows a notification.
`refresh`	none	Reloads the record or list, so your changes show immediately.
`open_url`	`url` (on an allowed domain)	Opens the URL in a new tab.
`open_iframe`	`url` (on an allowed domain), `presentation` (`drawer` or `modal`)	Opens your page inside Campfire, with the same context token. Use this when you need input from the person.

An empty 200 response is fine too.

The invoice after Calculate tax, with $174.00 of tax on the hardware line and a success toast

Your endpoint has timeout_ms to respond: 8,000 ms by default, adjustable from 1,000 to 10,000. Campfire doesn’t follow redirects and reads at most 64 KB of the response. If your server returns a non-2xx status, invalid JSON, or an unknown effect, the person sees “<App> could not complete this action.” If it times out, they see “<App> did not respond in time.” Either way, the failure is recorded on your app’s Activity tab. List header buttons act on the selected rows. object_ids contains up to 50 ids. Reply with one summary toast:

Two invoices selected on the invoice list with the Actions menu open showing Calculate FakeTax under FAKETAX

A toast reading FakeTax: Tax $174.00 written on 2 invoices

If your change needs approval in the workspace, the API answers 202 with a draft instead of saving the record. Tell the person it was submitted for approval rather than reporting success. FakeTax does this.

Iframe buttons

An iframe button opens your page in a drawer (default) or modal, sm, md (default), or lg wide. Campfire doesn’t add anything to the URL. Your page gets its context over the bridge instead:

The Tax breakdown drawer showing FakeTax's per-line breakdown with an Apply to invoice button

URL templates

URL templates can include these placeholders:

Placeholder	Value
`{{record.id}}`	The record’s id. Not available on `list_header` buttons; use `object_ids` from the request.
`{{record.number}}`	The invoice number, bill number, or journal entry reference.
`{{customer.id}}`	The workspace id.
`{{install.<key>}}`	A value from the workspace’s install config.

Values are URL-encoded. A placeholder at the very start of a template, such as {{install.base_url}}/report, is inserted as-is, so each workspace can point at its own host. The result must still be on an allowed domain.

Visibility rules

Show only when takes up to five rules, all of which must match. Each rule is a field, an operator (eq, neq, in, not_in), and a value:

Object	Fields you can test
Invoice	`payment_status`, `currency`, `tax_exempt`
Bill	`payment_status`, `currency`, `bill_type`, `source`
Journal entry	`type`, `currency`, `created_automatically`
Vendor	`vendor_type`, `is_1099`, `country`

FakeTax shows Calculate tax only on draft and open invoices:

"visible_when": [{"field": "payment_status", "op": "in", "value": ["draft", "open"]}]

Campfire checks the rules again when the button is clicked. On a list, the button shows if any selected row matches, and only the matching rows are sent to you.

How buttons are styled

In your own workspace, buttons get the style you chose. In other workspaces, they start as menu items until a workspace admin promotes them. To keep pages tidy, each page area shows at most one primary and two secondary app buttons. Extras become menu items. If the page already has its own primary button, yours becomes secondary. App buttons are drawn in Campfire’s partner color so people can tell them apart from Campfire’s own.

Who sees a button

A person sees your button only if:

someone in their workspace has connected your app,
they can view that kind of record, and
a workspace admin hasn’t switched the button off or limited it to other roles.

Clicks are limited to 30 per minute per person.

Panels

Panels embed one of your pages as a tab next to Campfire’s own tabs. Manage them on the Panels tab.

Field	Notes
Label	The tab’s title, up to 60 characters.
Key	Unique within the app.
Object	`invoice`, `bill`, `journal_entry`, or `vendor`.
Placements	One or more of `list`, `detail`, and `edit`.
URL template	The page to embed. `{{record.*}}` isn’t available when `list` is one of the placements.
Show only when	The same visibility rules as buttons.

An app can have up to 20 panels.

Where panels appear today: invoices (list page, invoice page, edit modal) and bills (list page, edit modal).

FakeTax’s breakdown on an invoice page:

An invoice page with the FakeTax tab selected, showing the tax breakdown embedded in the page

And its settings on the invoice list. A list panel’s token names no record:

The invoice list with a FakeTax tab showing default rate and auto-calculate settings

Panels load in a sandboxed iframe (allow-scripts allow-forms allow-same-origin allow-popups, no referrer). They start 480 px tall and can resize themselves between 120 and 2,000 px over the bridge. Navigation adds a section to Campfire’s main sidebar, after Campfire’s own sections. Each page opens full-width inside Campfire, under a header with the page’s label and your app’s name. Manage it on the Navigation tab.

The Navigation tab with a FakeTax section containing Jurisdictions, Tax codes and Settings pages

The FakeTax section expanded in Campfire's sidebar with the Jurisdictions page open, showing nexus states and rates

A top-level entry with no URL is a section that groups pages. A top-level entry with a URL is a page on its own. If it also has pages under it, it shows first as Overview.
Pages nest one level deep. An app can have up to 30 entries in total, and keys must be unique across all of them.
Labels are up to 40 characters. Icons are Lucide names, as for buttons.
URL templates can use {{customer.id}} and {{install.<key>}}, but not {{record.*}}.
Pages are framed exactly like panels, start 720 px tall, and receive a context token with surface: "nav".

Everyone in a connected workspace sees your navigation, unless an admin switches it off.

The FakeTax Tax codes page embedded full-width in Campfire

The manage link and onboarding

Manage URL

Set Manage URL on the app’s Details tab to give connected workspaces a way into your app’s settings. The connection page then shows Manage in <App>:

The FakeTax connection page with Manage in FakeTax and Disconnect buttons, and switches for each button

Clicking it opens your Manage URL in a new tab with a context token (surface: "manage", object_type: "workspace"):

https://your-app.com/manage?cf_ctx=eyJhbGciOiJIUzI1NiIs...

Verify the token, then sign the person in to your app for that workspace. FakeTax uses this as its sign-in, so people never need a separate FakeTax account.

Manage URL is part of the app’s versioned details, so a change takes effect when you promote it.

Onboarding after connect

When someone clicks Connect on your app’s connection page, Campfire sends them to your Connect URL with a return_to parameter holding the Campfire page they came from:

https://your-app.com/connect?return_to=https%3A%2F%2Fapp.meetcampfire.com%2Fv2%2Fsettings%2Fconnections%2Fapps%2F...

Use that to run your own setup after the OAuth callback, then send the person back. Only redirect to return_to if it starts with Campfire’s own origin, to avoid an open redirect. FakeTax’s onboarding asks where the workspace collects tax, then uses its app token to create a Tax code custom field on invoice lines, then returns to Campfire:

FakeTax setup step 1, choosing states with nexus and a default tax code

FakeTax setup done, with a Return to Campfire button

Install config

Your app often needs settings per workspace rather than per person. Install config stores a small set of strings on Campfire, one set per app per workspace. Read and write it with any of the workspace’s OAuth tokens:

curl https://api.meetcampfire.com/ca/api/v1/oauth-app-install/config \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "customer_id": 52,
  "customer_name": "Example Co",
  "user": {"id": 31017, "name": "Jordan Lee", "email": "jordan@example.com"},
  "install_config": {"default_rate": "5.00", "auto_calculate": "false"}
}

PUT the same path with {"install_config": {...}} to replace the whole object. Limits: up to 32 keys, lowercase identifiers, string values only, and 2,048 characters in total. This endpoint only accepts OAuth app tokens.

The GET response tells you which workspace and person a token belongs to, so it’s also a handy “who am I” call right after the token exchange.

Values fill {{install.<key>}} placeholders in your URL templates.

Event subscriptions

Event subscriptions notify your server when records change in every workspace where your app is connected. Manage them on the Events tab.

The Events tab with one subscription to Invoice and CreditMemo topics, with Send Test, Edit and Delete

Each subscription has an endpoint URL (on an allowed domain; only {{customer.*}} and {{install.*}} placeholders) and a list of topics. An app can have up to 10 subscriptions.

Topics	Scope your app needs
`Invoice.created`, `.updated`, `.deleted`, `.paid`, `.payment`	`invoices:read`
`Bill.created`, `.updated`, `.deleted`, `.paid`, `.payment`	`bills:read`
`CreditMemo.`, `CreditMemoLine.` (`created`, `updated`, `deleted`)	`credit_memos:read`
`DebitMemo.`, `DebitMemoLine.` (`created`, `updated`, `deleted`)	`debit_memos:read`
`JournalEntry.created`, `.updated`, `.deleted`	`journal_entries:read`
`Contract.created`, `.updated`, `.deleted`	`contracts:read`

Every topic must be covered by your app’s permissions. In each workspace, an event is only sent if someone there has granted a scope that covers it. Events are thin: they say what changed, not the new values. Re-read the record through the API with that workspace’s token:

POST /events HTTP/1.1
Content-Type: application/json
Campfire-App-Id: 0ca4c60f-db0a-4bc3-9efa-d2dec4292130
Campfire-Delivery-Kind: event
Campfire-Webhook-Request-Timestamp: 1791990000
Campfire-Webhook-Signature-v1: 9a7f42...

{
  "kind": "event",
  "topic": "Invoice.updated",
  "id": 18545770,
  "changed_fields": ["tax"],
  "customer": {"id": 52},
  "occurred_at": "2026-10-14T18:26:06Z"
}

changed_fields is empty for .deleted events. Send Test posts an example with "test": true and "id": 0. Delivery. Events are sent after the change is committed, with a 10-second timeout. Timeouts, connection failures, 429 and 5xx responses are retried up to 5 times, with exponential backoff starting at 1 minute and capped at 1 hour. Other 4xx responses are not retried. Respond 2xx quickly and do slow work in the background.

If your app writes to the record it was notified about, that write produces another .updated event. Use changed_fields (or remember what you just wrote) to avoid loops.

App events vs. workspace webhooks

	App event subscriptions	Workspace webhooks
Defined	Once, on the app	Per workspace
Delivered for	Every connected workspace	The workspace that created it
Payload	Thin: topic, id, changed fields	The full record, plus changes
Signed with	The app’s signing secret	That webhook’s own token
Ends when	The workspace’s last connection is removed	The webhook is deleted

Security

Verifying signatures

Every webhook button call and event delivery has these headers:

Header	Value
`Campfire-App-Id`	Your app’s id.
`Campfire-Delivery-Kind`	`slot` (button) or `event`.
`Campfire-Webhook-Request-Timestamp`	Unix seconds.
`Campfire-Webhook-Signature-v1`	Hex HMAC-SHA256 of `"{timestamp}:{raw body}"`, keyed with the full signing secret (including `whsec_`).
`Campfire-Webhook-Signature-v1-Previous`	The same, with the previous secret. Sent for 24 hours after a rotation.

Accept a request when either signature header matches, and reject timestamps more than 5 minutes off. Always compute the HMAC over the raw body bytes, before parsing the JSON.

import hashlib, hmac, time

def verify(headers, body: bytes, secrets: list[str]) -> bool:
    ts = headers.get("Campfire-Webhook-Request-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    sent = [s for s in (headers.get("Campfire-Webhook-Signature-v1"),
                        headers.get("Campfire-Webhook-Signature-v1-Previous")) if s]
    for secret in secrets:
        expected = hmac.new(secret.encode(), ts.encode() + b":" + body, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, s) for s in sent):
            return True
    return False

import crypto from "node:crypto";

export function verify(headers, rawBody, secrets) {
  const ts = headers["campfire-webhook-request-timestamp"] ?? "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const sent = [headers["campfire-webhook-signature-v1"], headers["campfire-webhook-signature-v1-previous"]].filter(Boolean);
  return secrets.some((secret) => {
    const expected = crypto.createHmac("sha256", secret).update(`${ts}:`).update(rawBody).digest("hex");
    return sent.some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
  });
}

Context tokens

Whenever Campfire sends a person to your app, it includes a context token: on link buttons and the manage link as cf_ctx, in webhook bodies as context_token, and to embedded pages over the bridge. It’s an HS256 JWT signed with your signing secret, valid for 5 minutes:

{
  "iss": "campfire",
  "aud": "YOUR_CLIENT_ID",
  "jti": "6f0d8a8e-...",
  "iat": 1791990000,
  "exp": 1791990300,
  "customer_id": 52,
  "user_id": 31017,
  "slot_key": "view",
  "object_type": "invoice",
  "object_ids": ["18545770"],
  "surface": "detail_header"
}

Opened from	`surface`	`slot_key`	`object_type` / `object_ids`
A button	`detail_header`, `list_header`, or `row_menu`	The button’s key	The record type and ids
A panel	`panel:list`, `panel:detail`, or `panel:edit`	The panel’s key	The record type; ids except on lists
A navigation page	`nav`	The entry’s key	`workspace`, `[]`
The manage link	`manage`	`manage`	`workspace`, `[]`

To verify one:

Check the signature against your current and previous signing secrets.
Require exp, iat, jti, aud, and iss. Check that aud is your client ID and iss is campfire.
Check that the record you’re about to show is in object_ids.
Record the jti and refuse it if you’ve seen it before. Campfire doesn’t enforce single use for you.

import jwt

claims = jwt.decode(
    token, signing_secret, algorithms=["HS256"],
    audience=CLIENT_ID, issuer="campfire",
    options={"require": ["exp", "iat", "jti", "aud", "iss"]},
)

A context token proves who opened your page and what they were looking at. It is not an API token. Make API calls with the workspace’s OAuth access token, which you store when someone connects your app.

The bridge

Pages embedded in drawers, modals, panels and navigation talk to Campfire with window.postMessage. Campfire only accepts messages from your frame’s origin, and you should only accept messages from Campfire’s origin (https://app.meetcampfire.com) sent by window.parent. Every message from your page has this shape:

{ source: "campfire-app-bridge", version: 1, type: "...", payload: { ... }, requestId: "..." }

`type`	`payload`	What Campfire does
`ready`	none (send a `requestId`)	Replies with the context (below).
`toast`	`{level, message}`	Shows a notification.
`refresh`	none	Reloads the record or list behind your page.
`resize`	`{height}`	Sets the frame’s height (120 to 2,000 px).
`close`	none	Closes the drawer or modal. Ignored in panels and pages.
`open_url`	`{url}`	Opens a URL on your frame’s origin in a new tab.

Campfire’s reply to ready:

{
  source: "campfire-host", version: 1, type: "context", requestId: "...",
  payload: { context_token: "eyJ...", object_type: "invoice", object_ids: ["18545770"],
             surface: "detail_header", theme: "light" }
}

Send the context_token to your own server to verify it, then load your data. FakeTax’s static/app-bridge.js is a 70-line wrapper you can copy. It provides ready(), toast(), refresh(), resize(), autoResize(), close(), and openUrl().

An embedded page usually makes several requests to your server, but the context token is single-use. FakeTax claims the token on the first request and opens a short-lived server-side session for the frame. Later requests use that session.

What workspace admins control

On the connection page (Settings > Connections, then your app), a workspace admin can switch off each button, panel, navigation entry and subscription, and change a button’s style for their workspace. These settings survive changes to your app, because they’re matched by key (and by endpoint URL for subscriptions).

The connection page's Panels, Navigation and Subscriptions switches and the connection activity log

Activity and testing

The Activity tab on your app’s page lists the latest 100 button clicks and event deliveries across every workspace, with status, HTTP code and response time. Use it to debug failures:

The Activity tab listing recent calculate, view, breakdown and calculate-bulk button clicks with status, HTTP code and timing

To test without real records, use Send Test on a subscription.

Extensions are not versioned. Allowed domains, the signing secret, buttons, panels, navigation and event subscriptions take effect in every connected workspace as soon as you save. Only the app’s details and permissions go through versions. Test changes in your own workspace with a separate development app before you change the one your customers use.

Limits

Item	Limit
Buttons per app	50
Panels per app	20
Navigation entries per app	30 (one level of nesting)
Event subscriptions per app	10
Allowed domains	20
Webhook button timeout	1,000 to 10,000 ms (default 8,000)
Webhook response size	64 KB
Effects per response	4
Rows per list-header click	50
Clicks and panel opens	30 per minute per person
Context token lifetime	5 minutes
Install config	32 keys, 2,048 characters, string values

Getting started

Guides

Extending Campfire with your app

FakeTax sample app

App manifest

The sample app: FakeTax

Before you start

Buttons

Link buttons

Webhook buttons

Iframe buttons

URL templates

Visibility rules

How buttons are styled

Who sees a button

Panels

Navigation

The manage link and onboarding

Manage URL

Onboarding after connect

Install config

Event subscriptions

App events vs. workspace webhooks

Security

Verifying signatures

Context tokens

The bridge

What workspace admins control

Activity and testing

Limits

FakeTax sample app

App manifest

​The sample app: FakeTax

​Before you start

​Buttons

​Link buttons

​Webhook buttons

​Iframe buttons

​URL templates

​Visibility rules

​How buttons are styled

​Who sees a button

​Panels

​Navigation

​The manage link and onboarding

​Manage URL

​Onboarding after connect

​Install config

​Event subscriptions

​App events vs. workspace webhooks

​Security

​Verifying signatures

​Context tokens

​The bridge

​What workspace admins control

​Activity and testing

​Limits

The sample app: FakeTax

Before you start

Buttons

Link buttons

Webhook buttons

Iframe buttons

URL templates

Visibility rules

How buttons are styled

Who sees a button

Panels

Navigation

The manage link and onboarding

Manage URL

Onboarding after connect

Install config

Event subscriptions

App events vs. workspace webhooks

Security

Verifying signatures

Context tokens

The bridge

What workspace admins control

Activity and testing

Limits