Webhooks and API reference

Overview

Two kinds of destination. A primary webhook URL receives every event, unsigned. Any number of webhook endpoints can be added on top, each with an optional per-event filter and an HMAC signing secret. Both are configured under Settings → Integrations. Zapier subscribes through the REST-hook endpoints below automatically.

Authentication

Settings → Integrations → API key issues a per-company bearer key (btk_…). Only a hash is stored; the plaintext is shown once. Send it as Authorization: Bearer btk_… (or X-API-Key) to the REST endpoints. Regenerating the key revokes the old one.

Webhooks

POST, Content-Type: application/json, User-Agent: BidTorch/1.0. Every payload carries event, event_id (a uuid, stable across retries — the de-duplication key), sent_at, and an org block with the company's id, name, phone and email.

Durable, at-least-once delivery. Every event is persisted and attempted immediately. A delivery that fails (network, timeout, or a non-2xx response) is retried with exponential backoff — about a minute at first, capped at six hours, up to eight attempts — before being parked. Because retries mean an event can arrive more than once, consumers must de-duplicate on event_id: treat the webhook as a trigger, not a ledger. Ten-second timeout per endpoint; endpoints fire concurrently, so one slow endpoint never blocks another. Each endpoint shows its last delivery time and HTTP status in Settings.

Signing. Deliveries to an endpoint with a secret carry:

X-BidTorch-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

Verify by recomputing the HMAC over "<t>.<raw body>" with the secret shown when the endpoint was added, and optionally rejecting a stale t. The primary webhook URL and Zapier subscriptions are unsigned; Zapier's per-Zap target URLs are unguessable, which is the standard REST-hook trust model.

Events

Every event, when it fires, and the root key of its payload.

Every job.* payload also carries an assignee object (id, name, email, phone, role — or null when unassigned), which is what a scenario reads to text or email the assigned tech on job.assigned.

Payloads

quote.accepted and quote.signed fire together — signing is acceptance — so subscribe to one. Their payload includes company-side economics (cost basis, gross profit, margin) that never appear on the public quote. pdf_url is the rendered PDF of the signed quote, a signed download link valid about seven days, ample for a scenario to run and retry. quote.sent and quote.expired carry a slim quote object with no economics.

{
  "event": "quote.accepted",
  "sent_at": "2026-06-11T18:00:00Z",
  "org": { "id": "…", "name": "…", "phone": "…", "email": "…", "address": "…", "website": "…" },
  "quote": {
    "id": "…", "quote_number": "AP-2026-014", "status": "accepted",
    "customer_name": "…", "customer_company": null, "customer_email": "…", "customer_phone": "…",
    "customer_address": "…", "job_address": "…",
    "subtotal": 0, "tax_amount": 0, "total": 0,
    "cost_basis": 0, "gross_profit": 0, "margin_pct": 0,
    "accepted_option_id": "…", "accepted_at": "…", "signed_at": null,
    "has_signature": false, "share_token": "…", "public_path": "/q/…",
    "public_url": "https://…/q/…", "pdf_url": "https://…/q/…?pdf=1", "notes": null
  },
  "accepted_option": {
    "id": "…", "tier": "better", "name": "…",
    "subtotal": 0, "svc_call_amount": 0, "total": 0,
    "cost_basis": 0, "margin_pct": 0, "notes": null,
    "items": [
      { "item_type": "service", "description": "…", "qty": 1, "unit": "ea",
        "unit_cost": 0, "markup_pct": 0, "line_total": 0,
        "store": null, "po_number": null, "note": null }
    ]
  }
}

{
  "event": "job.completed",
  "sent_at": "…",
  "org": { "id": "…", "name": "…", "phone": "…", "email": "…" },
  "job": {
    "id": "…", "job_number": "JOB-2026-007", "title": "…", "status": "completed",
    "scheduled_at": "…", "started_at": "…", "completed_at": "…",
    "customer_name": "…", "customer_email": "…", "customer_phone": "…",
    "job_address": "…", "total": 0, "notes": null, "quote_id": "…", "created_at": "…"
  }
}

{
  "event": "invoice.paid",
  "sent_at": "…",
  "org": { "id": "…", "name": "…", "phone": "…", "email": "…" },
  "invoice": {
    "id": "…", "invoice_number": "…", "status": "paid",
    "customer_name": "…", "customer_email": "…", "customer_phone": "…",
    "customer_address": "…", "job_address": "…",
    "subtotal": 0, "tax_amount": 0, "amount_due": 0, "amount_paid": 0,
    "stripe_payment_link_url": null, "due_date": "…",
    "sent_at": "…", "paid_at": "…", "share_token": "…", "public_path": "/i/…", "org_id": "…"
  },
  "items": [
    { "description": "…", "qty": 1, "unit": "ea", "unit_price": 0, "line_total": 0, "sort_order": 0 }
  ]
}

{
  "event": "lead.created",
  "sent_at": "…",
  "org": { "id": "…", "name": "…", "phone": "…", "email": "…" },
  "lead": {
    "id": "…", "status": "new", "name": "…", "email": "…", "phone": "…",
    "address": "…", "service_type": "…", "message": "…", "source": "…", "created_at": "…"
  }
}

REST endpoints

The small authenticated surface: the REST-hook subscribe/unsubscribe pair Zapier uses, a sample payload per event for a trigger test, and the two inbound sinks.

Inbound leads and SMS

An outside form, chatbot, phone system or Zap can create a lead. It lands in the pipeline as new and fires lead.created:

curl -X POST https://bidtorch.com/api/leads/inbound \
  -H "Authorization: Bearer btk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Pat Doe","phone":"317-555-0100","service_type":"Water heater","message":"No hot water since this morning","source":"website"}'

Two-way SMS has two transports, chosen per company. The default is webhook-based: a rep sends from the Messages inbox, BidTorch stores it and fires sms.outbound for your scenario to carry to Twilio; a reply comes back through POST /api/sms/inbound. The native transport talks to the company's own Twilio account directly with real delivery status, and inbound messages arrive on a signed, per-company Twilio webhook URL shown in Settings. Carrier registration for business texting applies either way.

Native integrations

• Stripe — bring your own key; deposits on accept and invoice pay-links. Saving the key registers the payment-notification receiver on your account.
• Square — connect the account; a per-company signed webhook receiver reconciles payments to the invoice.
• QuickBooks Online — OAuth connect; sent invoices push to QuickBooks and payments recorded there reconcile the BidTorch invoice. Pulling customers or estimates into BidTorch is not built in.
• Calendar — a read-only ICS feed (Settings → Calendar feed) that Google, Apple and Outlook subscribe to. Regenerating the token revokes every previously shared URL.
• Everything else — HubSpot, Google Drive, Slack, review tools: webhook plus Make or Zapier.