TechSales Developers

Overview

The TechSales GTM API gives your own systems read access to one workspace: contacts, lists and their rows, campaigns, classified replies, account signals, the do-not-contact list and list preparation jobs. The one thing it writes is a contact's link to its id in your CRM. Outbound webhooks tell you when something changes, so you rarely need to poll.

• Base URL: https://app.techsalestr.com/v1. JSON over HTTPS.
• A list answers { object: "list", data, has_more, next_cursor, request_id }; a record answers its fields with object and request_id; an error answers { error: { code, message, request_id } }.
• Timestamps are ISO 8601 in UTC. Every response carries an X-Request-Id header.
• The machine-readable description is the OpenAPI 3.1 document (public, no key needed): import it into Postman, Insomnia or a client generator.

Quickstart

1. In the app, open Settings → Developer & Integrations (an agency managing a client: that client's Client settings → Developer & Integrations). The tab is for workspace admins, and the API is on every paid plan.
2. Under API keys, name the key (for example "CRM sync"), tick the scopes it needs, optionally pick an expiry date, and create it.
3. Copy the key from the dialog. It is shown once and can't be shown again; keep it in your secret store, never in browser code.
4. Make your first call:

export TECHSALES_API_KEY="tsk_live_…"

curl -s "https://app.techsalestr.com/v1/contacts?limit=5" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

A 200 with a data array means the key works. A 401 or 403 is explained under Troubleshooting.

Authentication

Send the key as a bearer token on every request: Authorization: Bearer <key>. A key looks like tsk_live_<prefix>_<secret>. It belongs to one workspace and decides which workspace a request reads; nothing in the request can change that.

• Shown once. The full key appears only in the dialog right after you create or rotate it. Afterwards the app shows its prefix and dots; we store only a hash of the secret.
• Rotation. Rotate gives the key a new secret and keeps its prefix. The previous secret keeps working for 24 h, so you can switch a running integration without downtime.
• Revocation. Revoke stops the key at once: the next request with it gets 401.
• Expiry. A key can carry an expiry date; after it, the key answers 401.
• Plan. The plan is checked on every request: a workspace without the API on its plan gets 403 feature_not_available.
• A workspace can have 10 live keys. Use one per system.

Scopes

A key carries scopes, and each endpoint needs exactly one. A key without it gets 403 insufficient_scope. Give each key only what its system reads.

Pagination and incremental sync

Lists page by cursor, never by offset. limit sets the page size (1 to 200, default 50). Each page returns has_more and next_cursor; pass next_cursor back as ?cursor= exactly as it came. A cursor is opaque: don't build or edit one. Send the same filters with every page.

Use the _since filter for the first run (or to recover a window), then the cursor. The filters each list accepts:

# First run: everything updated since a date you choose.
curl -s "https://app.techsalestr.com/v1/contacts?limit=200&updated_since=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

# Every later call: the next_cursor you stored, passed back exactly as it came.
curl -s "https://app.techsalestr.com/v1/contacts?limit=200&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

Rate limits

Each key may make 120 requests a minute, and all of a workspace's keys together 600. Windows are fixed, 1 min long. Every authenticated response says where you stand:

On 429 rate_limited, wait Retry-After seconds and try again. The public OpenAPI document has a separate, per-address limit.

Errors

An error answers with its HTTP status and a body with a stable code, a readable message and the request_id. Branch on the code, not the message; quote the request id when you contact us.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have the contacts:read scope.",
    "request_id": "req_0123456789abcdef0123456789abcdef"
  }
}

Endpoint reference

Generated from the OpenAPI document. Parameters marked * are required.

curl -s "https://app.techsalestr.com/v1/openapi.json"

curl -s "https://app.techsalestr.com/v1/openapi.json"

curl -s "https://app.techsalestr.com/v1/contacts?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/contacts" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/contacts/00000000-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/contacts/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/contacts/00000000-0000-4000-8000-000000000101/external-ids" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/contacts//external-ids" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s -X PUT "https://app.techsalestr.com/v1/contacts/00000000-0000-4000-8000-000000000101/external-ids/hubspot" \
  -H "Authorization: Bearer $TECHSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-12345","sync_status":"synced"}'

curl -s -X PUT "https://app.techsalestr.com/v1/contacts//external-ids/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "crm-12345",
  "sync_status": "synced"
}'

curl -s -X DELETE "https://app.techsalestr.com/v1/contacts/00000000-0000-4000-8000-000000000101/external-ids/hubspot" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s -X DELETE "https://app.techsalestr.com/v1/contacts//external-ids/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/lists?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/lists" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/lists/00000000-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/lists/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/lists/00000000-0000-4000-8000-000000000101/rows?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/lists//rows" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/campaigns?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/campaigns" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/campaigns/00000000-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/campaigns/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/replies?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/replies" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/replies/00000000-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/replies/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/signals?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/signals" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/signals/00000000-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/signals/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/suppression?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/suppression" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/jobs?limit=50" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/jobs" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/jobs/00000000-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

curl -s "https://app.techsalestr.com/v1/jobs/" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

Webhooks

A webhook endpoint is a URL of yours that receives a signed POST when something happens in the workspace. Every event is written in the same database transaction as the change it describes, then delivered at least once. The payload is deliberately small: ids, the changed fields and the state. Read anything else from the API with the id.

Setup

1. Build a receiver: an https:// URL on a public host name, on the default port, without credentials in it. Private, loopback and internal addresses are refused, when you save and again before every attempt. Redirects are not followed.
2. In the app, open Settings → Developer & Integrations → Webhooks and add the endpoint: the URL, an optional description, and at least one event. A workspace can have 10 endpoints.
3. Copy the signing secret (whsec_…) from the dialog. Like an API key it is shown once; keep it with your receiver's secrets.
4. Press Send test event and check that your receiver verifies the signature and answers 2xx.
5. Watch the delivery log under Webhook deliveries: every try, its answer and what is next.

Every delivery is a POST with a JSON body and these headers:

The body is an envelope: id, type, version (the payload version, currently 2026-11-02), created_at, workspace_id, resource: { type, id } and data. A test event also has test: true; an endpoint with a field mapping also gets mapped on contact events (see Field mapping).

Event catalog

20 event types in 6 categories. Open one for exactly when it fires and an example body.

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "contact.created",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "contact",
    "id": "00000000-0000-4000-8000-000000000101"
  },
  "data": {
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "company": "Acme",
    "job_title": "CTO",
    "linkedin_url": null,
    "status": "new",
    "source": "email",
    "created_at": "2026-11-02T09:30:00.000Z"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "contact.updated",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "contact",
    "id": "00000000-0000-4000-8000-000000000101"
  },
  "data": {
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "changed_fields": [
      "job_title",
      "company"
    ],
    "current": {
      "job_title": "CEO",
      "company": "Acme Holding"
    }
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "contact.status_changed",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "contact",
    "id": "00000000-0000-4000-8000-000000000101"
  },
  "data": {
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "from": "meeting_booked",
    "to": "qualified",
    "by": "person",
    "at": "2026-11-02T09:30:00.000Z"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "contact.deleted",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "contact",
    "id": "00000000-0000-4000-8000-000000000101"
  },
  "data": {
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "reason": "merged",
    "merged_into": "00000000-0000-4000-8000-000000000301",
    "deleted_at": "2026-11-02T09:30:00.000Z"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "suppression.created",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "suppression",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "suppression_id": "00000000-0000-4000-8000-000000000301",
    "type": "domain",
    "value": "acme.io",
    "created_at": "2026-11-02T09:30:00.000Z"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "suppression.deleted",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "suppression",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "suppression_id": "00000000-0000-4000-8000-000000000301",
    "type": "email",
    "value": "[email protected]"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "list.created",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "status": "draft",
    "created_at": "2026-11-02T09:30:00.000Z"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "list.processing_started",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "from": "queued",
    "to": "running"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "list.processing_completed",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "from": "running",
    "to": "ready"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "list.processing_needs_review",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "from": "running",
    "to": "needs_review"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "list.processing_partially_completed",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "from": "running",
    "to": "partial"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "list.processing_failed",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "from": "running",
    "to": "failed"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "campaign.approved",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "campaign",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "campaign_id": "00000000-0000-4000-8000-000000000301",
    "name": "Fintech CTOs: email",
    "list_id": "00000000-0000-4000-8000-000000000201",
    "from": "pending_approval",
    "to": "approved"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "campaign.rejected",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "campaign",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "campaign_id": "00000000-0000-4000-8000-000000000301",
    "name": "Fintech CTOs: email",
    "list_id": "00000000-0000-4000-8000-000000000201",
    "from": "pending_approval",
    "to": "rejected"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "campaign.launched",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "channel": "primary",
    "from": "draft",
    "to": "active"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "campaign.paused",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "list",
    "id": "00000000-0000-4000-8000-000000000201"
  },
  "data": {
    "list_id": "00000000-0000-4000-8000-000000000201",
    "name": "Fintech CTOs Q4",
    "channel": "secondary",
    "from": "active",
    "to": "paused"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "reply.received",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "message",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "message_id": "00000000-0000-4000-8000-000000000301",
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "channel": "email",
    "received_at": "2026-11-02T09:30:00.000Z"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "reply.classified",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "reply",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "reply_id": "00000000-0000-4000-8000-000000000301",
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "channel": "email",
    "intent": "interested",
    "confidence": 0.92,
    "action": "propose_meeting",
    "requires_review": false
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "reply.sent",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "sent_reply",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "sent_reply_id": "00000000-0000-4000-8000-000000000301",
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "platform": "instantly"
  }
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "intent.signal_detected",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "signal",
    "id": "00000000-0000-4000-8000-000000000301"
  },
  "data": {
    "signal_id": "00000000-0000-4000-8000-000000000301",
    "account_id": "00000000-0000-4000-8000-000000000201",
    "contact_id": null,
    "kind": "funding",
    "level": "company",
    "title": "Acme raised a Series B",
    "source": "news",
    "detected_at": "2026-11-02T09:30:00.000Z"
  }
}

Verifying signatures

Every delivery is signed with your endpoint's secret. The header is X-TechSales-Signature: t=<timestamp>,v1=<signature>, where the signature is the hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with the whole secret string (including whsec_) as UTF-8.

1. Read the raw request body as bytes, before any JSON parsing or re-serialising.
2. Split the header on commas; take t and every v1 (there can be two).
3. Reject a t more than 300 seconds from your clock (replay protection).
4. Compute the HMAC for each secret you hold and compare it with each v1 in constant time. Any match is valid.

import crypto from "node:crypto";
import express from "express";

// During a secret rotation, list the new secret and the old one: either may sign.
const SECRETS = [process.env.TECHSALES_WEBHOOK_SECRET];
const TOLERANCE_SECONDS = 300;

export function verifySignature(header, rawBody, secrets, nowMs = Date.now()) {
  if (!header) return false;
  let t = null;
  const v1 = [];
  for (const part of header.split(",")) {
    const [k, v = ""] = part.trim().split("=", 2);
    if (k === "t" && /^\d{1,12}$/.test(v)) t = Number(v);
    else if (k === "v1" && /^[0-9a-f]{64}$/.test(v)) v1.push(v);
  }
  if (t === null || v1.length === 0) return false;
  if (Math.abs(Math.floor(nowMs / 1000) - t) > TOLERANCE_SECONDS) return false; // replay
  for (const secret of secrets) {
    const expected = crypto
      .createHmac("sha256", secret) // the whole whsec_… string is the key
      .update(`${t}.${rawBody}`, "utf8")
      .digest();
    for (const sig of v1) {
      const given = Buffer.from(sig, "hex");
      if (given.length === expected.length && crypto.timingSafeEqual(given, expected)) return true;
    }
  }
  return false;
}

const app = express();
// The raw body: verify the exact bytes that were signed, before any JSON parsing.
app.post("/webhooks/techsales", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifySignature(req.get("X-TechSales-Signature"), raw, SECRETS)) return res.status(400).send("bad signature");
  const event = JSON.parse(raw);
  res.sendStatus(200); // answer fast, then work
  queueForProcessing(event); // your code: dedupe on event.id, then handle
});

import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

# During a secret rotation, list the new secret and the old one: either may sign.
SECRETS = [os.environ["TECHSALES_WEBHOOK_SECRET"]]
TOLERANCE_SECONDS = 300

def verify_signature(header, raw_body: bytes, secrets, now=None) -> bool:
    if not header:
        return False
    t, v1 = None, []
    for part in header.split(","):
        k, _, v = part.strip().partition("=")
        if k == "t" and v.isdigit() and len(v) <= 12:
            t = int(v)
        elif k == "v1" and len(v) == 64:
            v1.append(v)
    if t is None or not v1:
        return False
    if abs(int(now if now is not None else time.time()) - t) > TOLERANCE_SECONDS:
        return False  # replay
    signed = str(t).encode() + b"." + raw_body
    for secret in secrets:
        # the whole whsec_... string is the key
        expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, sig) for sig in v1):
            return True
    return False

app = Flask(__name__)

@app.post("/webhooks/techsales")
def techsales_webhook():
    raw = request.get_data()  # the exact bytes that were signed
    if not verify_signature(request.headers.get("X-TechSales-Signature"), raw, SECRETS):
        return "bad signature", 400
    event = json.loads(raw)
    queue_for_processing(event)  # your code: dedupe on event["id"], then handle
    return "", 200

Retries and auto-disable

Answer with a 2xx within 10 s; do the work after answering. What happens with other answers:

A delivery gets at most 8 attempts. The waits between them are 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h (each ±20 %), about 22.4 hours in all. After the last failed attempt the delivery is dead. Every attempt is in the delivery log, with its status code and the start of your answer.

Duplicates and order

• Delivery is at least once: the same event can arrive more than once (a retry after a timeout, a replay). It always has the same id, also in X-TechSales-Event-Id. Store processed ids with a unique key and skip repeats.
• Order is not guaranteed: a retry can arrive after a later event. Use the body's created_at, or read the current record from the API, before overwriting newer data.
• The body is the same on every retry and replay, except mapped, which is made when the attempt is sent (its mapping_version says which mapping made it).

Test events and replays

Send test event posts a webhook.test event to that one endpoint right away, signed like any other. It is never stored, never retried, not in the delivery log and does not count toward the endpoint's health; the app shows the answer. You can't subscribe to it.

{
  "id": "evt_0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
  "type": "webhook.test",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "endpoint",
    "id": "00000000-0000-4000-8000-000000000501"
  },
  "data": {
    "message": "This is a test event from TechSales. It is safe to ignore."
  },
  "test": true
}

From the delivery log you can replay one delivery, or every failed or dead delivery of the last 24 hours. A replay is a new delivery of the same event with the same event id, so your dedupe still applies. The endpoint must be on.

Field mapping

Your CRM names its fields its own way (FirstName, EmailAddress, a custom field). A field mapping, made in Settings → Developer & Integrations → Field mapping and attached to a webhook endpoint, sends contact fields under those names: that endpoint's contact events carry a mapped object ready to write into the CRM.

• Only fields TechSales holds can be mapped; nothing is invented to fill a destination.
• A value we don't have is left out of mapped.fields by default (on_missing: omit), so writing the object never blanks a value your CRM already holds. on_missing: null sends null instead, for a field you want cleared.
• A required field that is missing is listed in missing_required; the event is still delivered and your receiver decides.
• An event carries a partial contact (contact.updated holds what changed, contact.status_changed the stage), and the mapping applies to what is there, so a partial update stays partial.
• mapped is on contact.created, contact.updated and contact.status_changed. Other events have no mapped.

Transforms: none, trim, lowercase, uppercase, date_only, to_text. Each is allowed only on a source type it can't break (for example date_only on a date).

{
  "integration": "hubspot",
  "on_missing": "omit",
  "fields": [
    {
      "source": "first_name",
      "destination": "FirstName",
      "required": false,
      "transform": "none"
    },
    {
      "source": "last_name",
      "destination": "LastName",
      "required": false,
      "transform": "none"
    },
    {
      "source": "email",
      "destination": "Email",
      "required": true,
      "transform": "lowercase"
    },
    {
      "source": "company",
      "destination": "Company",
      "required": false,
      "transform": "none"
    },
    {
      "source": "job_title",
      "destination": "Title",
      "required": false,
      "transform": "none"
    },
    {
      "source": "linkedin_url",
      "destination": "LinkedIn_URL__c",
      "required": false,
      "transform": "none"
    },
    {
      "source": "external_id",
      "destination": "crm_id",
      "required": false,
      "transform": "none"
    }
  ]
}

{
  "id": "evt_3f1c2a9b8d7e4c6f9a0b1c2d3e4f5a6b",
  "type": "contact.created",
  "version": "2026-11-02",
  "created_at": "2026-11-02T09:30:00.000Z",
  "workspace_id": "00000000-0000-4000-8000-000000009001",
  "resource": {
    "type": "contact",
    "id": "00000000-0000-4000-8000-000000000101"
  },
  "data": {
    "contact_id": "00000000-0000-4000-8000-000000000101",
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "company": "Acme",
    "job_title": "CTO",
    "linkedin_url": null,
    "status": "new",
    "source": "email",
    "created_at": "2026-11-02T09:30:00.000Z"
  },
  "mapped": {
    "mapping_id": "00000000-0000-4000-8000-000000000601",
    "mapping_version": 1,
    "fields": {
      "FirstName": "Ada",
      "LastName": "Lovelace",
      "Email": "[email protected]",
      "Company": "Acme",
      "Title": "CTO"
    },
    "missing_required": []
  }
}

Here LinkedIn_URL__c and crm_id are left out: the contact has no LinkedIn URL and is not linked to a CRM record yet.

External ids

An external id links a contact to its record in one of your systems (the integration, a short name you choose such as hubspot or my_crm). Save it with PUT /v1/contacts/{id}/external-ids/{integration} after you create the record, and every later event or sync can update that record instead of creating another.

• The PUT is idempotent: the same call twice leaves one link.
• One record, one contact: an id already linked to a different contact in the same system is refused with 409 conflict.
• Find a contact by its CRM id with GET /v1/contacts?integration=…&external_id=…. The links are on every contact as external_links.
• A mapping with an integration can send the saved id as the external_id source field, so the receiver knows which record to update without a lookup.
• Match on these ids, never on email alone: people change addresses and share inboxes.
• Writing needs a key with the contacts:write scope; it writes nothing else.

# Save (or replace) the contact's id in your CRM. Idempotent.
curl -s -X PUT "https://app.techsalestr.com/v1/contacts/00000000-0000-4000-8000-000000000101/external-ids/hubspot" \
  -H "Authorization: Bearer $TECHSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "crm-12345", "sync_status": "synced"}'

# Find the contact behind a CRM id.
curl -s "https://app.techsalestr.com/v1/contacts?integration=hubspot&external_id=crm-12345" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

End-to-end integration: contacts into your CRM

The whole loop, from a new key to a CRM that stays in step, including what to do when your receiver was down.

1. Create a key with contacts:read and contacts:write (Quickstart).
2. Register a webhook pointing at your receiver and subscribe it to contact.created and contact.status_changed (Setup). Store the signing secret.
3. Attach a field mapping with your CRM's field names and an integration (for example hubspot), including external_id (Field mapping).
4. Receive and verify: read the raw body, check X-TechSales-Signature, answer 2xx within 10 s, then process (Verifying signatures).
5. Dedupe on the event id before doing anything (Duplicates and order).
6. Map: take mapped.fields, or map data yourself when no mapping is attached.
7. Upsert by external id: with a CRM id, update that record; without one, create the record and link it back with the PUT (External ids).
8. Handle retries: answer 5xx or time out only when you want the event again; a 4xx stops retries for that delivery (Retries).
9. Recover missed events with the API: run the sync loop over GET /v1/contacts with updated_since for the gap the first time, then with the stored cursor (Pagination). Upsert by the same external id, so a record seen twice stays one record.

# The REST calls the handler makes, one by one.
# 1. Is this contact already linked to a hubspot record?
curl -s "https://app.techsalestr.com/v1/contacts/$CONTACT_ID/external-ids" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

# 2. After creating the record in the CRM, link it back.
curl -s -X PUT "https://app.techsalestr.com/v1/contacts/$CONTACT_ID/external-ids/hubspot" \
  -H "Authorization: Bearer $TECHSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "'"$CRM_ID"'", "sync_status": "synced"}'

# 3. Catch up on anything missed (downtime, a disabled endpoint): the sync loop.
curl -s "https://app.techsalestr.com/v1/contacts?limit=200&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

# First run: everything updated since a date you choose.
curl -s "https://app.techsalestr.com/v1/contacts?limit=200&updated_since=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

# Every later call: the next_cursor you stored, passed back exactly as it came.
curl -s "https://app.techsalestr.com/v1/contacts?limit=200&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $TECHSALES_API_KEY"

CRM examples

The pattern is the same everywhere: map the fields, then upsert by external id. Keep the CRM record's id as the contact's external id under one integration name per CRM (hubspot, salesforce, pipedrive), and in the CRM keep the TechSales contact id in a custom field, so either side can find the other.

HubSpot

• Map to the contact property internal names above. Store the HubSpot record id with PUT …/external-ids/hubspot.
• On an event, update the record by that id; with none, create the contact, then save its id.

Salesforce

• Decide whether a TechSales contact becomes a Lead or a Contact; the field names above cover both, with Company on the Lead.
• Use the 18-character record id as the external id (…/external-ids/salesforce), or an External ID field of yours that holds the TechSales contact id and upsert on it.

Pipedrive

• A person's organization is its own record: find or create it by name, then link the person to it.
• Store the person id with …/external-ids/pipedrive; job title and LinkedIn URL need custom fields.

Troubleshooting

Still stuck? Quote the request_id (API) or the delivery id from the delivery log (webhooks) when you contact us.

Changelog

Current API version: 1.1.0. Webhook payload version: 2026-11-02.

• 2026-11-02 · External ids and field mappings 1.1.0

  Contacts can be linked to their ids in your systems (contacts:write, the only write scope), contacts can be found by those ids, and webhook endpoints can carry a field mapping.

• 2026-11-02 · Outbound webhooks webhooks 2026-11-02

  Signed event deliveries with retries, a delivery log, replays and test events.

• 2026-11-02 · Read API 1.0.0

  Read-only endpoints for contacts, lists, campaigns, replies, signals, the do-not-contact list and jobs, with API keys, scopes, rate limits and the OpenAPI document.