WRAPTORHelp & Docs

API & Webhooks — connect Wraptor to Zapier and your own tools

Who it's for

Owners (and the tech-comfortable manager) who want Wraptor talking to the rest of their stack: Zapier automations, a custom dashboard, a spreadsheet that pulls live numbers, or lead sources that push straight into the Lead Inbox. Pro plan only.

Where it fits

Outside the job workflow itself — this is the integration layer around it. Events fire from the same moments the in-app bell rings (new lead, stage change, quote approved, payment landed).

Overview

Two halves:

  • The REST API (https://wraptor.io/api/v1) lets outside software read your customers, jobs, quotes, invoices, and leads — and create customers and leads. Every request authenticates with an API key you mint in Settings.
  • Outbound webhooks push events to a URL you control the moment they happen, signed so your receiver can prove they came from Wraptor. This is what a Zapier trigger rides on.

The machine-readable spec lives at /api/v1/openapi.json.

Screens & navigation

Settings → API & Webhooks (under Integrations & Billing). One panel, two cards:

  • API Keys — every active key with its display prefix (wrk_live_a1b2…), name, and last-used time.
  • Webhook Endpoints — every registered URL with its subscribed events, on/off state, a send-test button, and the last 20 delivery attempts (status, HTTP code, error, attempt count).

Capabilities

API keys

  • Create — name it after what will hold it ("Zapier", "reporting sheet"). The full key is shown once, in a copy box. Only a fingerprint is stored; Wraptor cannot show it again.
  • Revoke — two-step inline confirm. Takes effect immediately.
  • Up to 10 active keys; each key is shop-wide (full access, no scopes yet).

REST API

  • Read (list + get by id): customers, jobs, quotes, invoices, leads.
  • Write: POST /customers, POST /leads (an API-created lead lands in the Lead Inbox and rings the bell, source "api" — shown under the Directory badge in this version).
  • Lists paginate by cursor (?limit= up to 100, ?cursor= from the previous page's next_cursor) and filter by ?updated_since= (ISO timestamp) — leads, which never change once captured, use their created time.
  • GET /me verifies a key and names the shop (Zapier's auth test).
  • 120 requests/minute per key; over the limit returns 429 with Retry-After.

Webhook events

job.created, job.stage_changed, quote.approved, proof.approved, document.signed, invoice.paid, invoice.deposit_paid, lead.created, booking.created, customer.created.

  • Subscribe — add a URL and pick events (none selected = all events). The signing secret (whsec_…) is shown once at creation.
  • Verify — each POST carries wraptor-id, wraptor-timestamp, and wraptor-signature: v1,<base64 HMAC-SHA256> over id.timestamp.body, keyed with your secret's base64 part — the svix scheme, so any svix client library verifies it by mapping the header names.
  • Retries — a failed delivery retries with backoff (2m, 8m, then every 15m) for up to 6 attempts. An endpoint whose last 3 deliveries all exhausted retries is auto-disabled; fix the URL and re-enable it.
  • Send test — fires a test.ping at one endpoint and reports the HTTP result inline.
  • Manage endpoints from the API too (/api/v1/webhooks — create returns the secret once; delete unsubscribes), which is the REST-hook shape Zapier expects.

Step-by-step tasks

  1. Connect a spreadsheet or dashboard

    1. Settings → API & Webhooks → Create key, named for the tool.
    2. Copy the key from the one-time box.
    3. Call GET https://wraptor.io/api/v1/jobs with header Authorization: Bearer wrk_live_….
    4. Follow next_cursor until it is null; poll with updated_since after.

  2. Get notified the moment a lead arrives

    1. Add a webhook endpoint with your receiver URL, subscribed to lead.created.
    2. Store the one-time secret; verify wraptor-signature on each POST.
    3. Click Test to confirm your receiver answers 2xx.

  3. Push leads in from an outside form

    1. POST /api/v1/leads with { "name": "...", "contact": "...", "vehicle": "...", "message": "..." }.
    2. The lead appears in Marketing → Lead Inbox and rings the bell.

Settings & permissions

  • Pro plan (and the grandfathered original Pro) only — Solo and below see an upgrade prompt, and existing keys stop authenticating if the subscription lapses.
  • Managing keys and endpoints requires the billing permission (owners by default).

Tips & common pitfalls

  • Copy secrets when shown. Keys and signing secrets appear exactly once. Lose one → revoke/delete and create a fresh one; nothing else re-reveals it.
  • Answer webhooks fast with a 2xx. Do your real work after responding — a slow receiver hits the 10s timeout and looks like a failure.
  • Use wraptor-id for idempotency. Retries reuse the same id; process each id once.
  • Localhost/private URLs are rejected — webhook receivers must be publicly reachable.
  • Deleting an endpoint stops its deliveries immediately; disabling keeps it listed so you can re-enable without re-sharing a secret.