Send events into a room

How it works

1. 1

   Install

   A room owner or manager installs an app from the marketplace. The room gets a connection key (conn_…) and a signing secret (whsec_…). Only owners and managers can see them.

2. 2

   Send

   Your system POSTs JSON events to the room's URL with the secret or an HMAC signature.

3. 3

   Apply

   ThinkNCollab verifies the request, stores the delivery, updates the room feed and, for failures and incidents, opens tasks on the room board.

Endpoint

POST https://www.thinkncollab.com/api/v1/integrations/webhook/:connectionKey
Content-Type: application/json

The body must be a JSON object up to 10 MB. Name the event in event(or eventType, or the X-Event-Type header).

Authentication

The connection key in the URL identifies the room and must be kept private. Add at least one of the checks below so a leaked URL alone is not enough.

Every request must carry a signature or the secret. Unsigned requests get 401, bodies over 256 KB get 413, and each room accepts up to 180 requests a minute per integration (429 after that).

To replace a leaked URL or secret, a room manager removes the integration and installs it again; that issues a new URL and secret. Partners can rotate the secret for every room using their app from the partner console.

Signing payloads

The signature covers the exact bytes you send. Serialise the body once, sign <timestamp>.<body>, and send that same body.

import crypto from "node:crypto";
const body = JSON.stringify({ event: "deploy.finished", service: "web", status: "success" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = "v1=" + crypto.createHmac("sha256", process.env.TNC_SECRET).update(`${timestamp}.${body}`).digest("hex");
await fetch(process.env.TNC_WEBHOOK_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-TNC-Timestamp": timestamp,
    "X-TNC-Signature": signature,
    "X-TNC-Delivery-Id": crypto.randomUUID(),
  },
  body,
});

Events by category

What happens to an event depends on the category of the installed app.

{
  "event": "issue.updated",
  "id": "ENG-4092",
  "title": "Rotate ingress secrets",
  "status": "In progress",
  "priority": "high",
  "updatedAt": "2026-10-11T09:30:00Z",
  "assigneeEmail": "dev@example.com"
}

{
  "event": "test.run.completed",
  "suite": "Checkout E2E",
  "total": 42,
  "passed": 41,
  "failed": 1,
  "skipped": 0,
  "durationMs": 12400,
  "branch": "main",
  "commit": "3f2c9e1",
  "failures": [
    {
      "name": "Applies coupon code",
      "message": "Expected 80 but received 100"
    }
  ]
}

{
  "event": "deployment.succeeded",
  "service": "auth-gateway",
  "environment": "production",
  "commit": "9b1d4c07",
  "commitAt": "2026-10-11T07:55:00Z",
  "startedAt": "2026-10-11T09:02:00Z",
  "finishedAt": "2026-10-11T09:06:30Z"
}

{
  "event": "custom.batch_completed",
  "service": "billing-worker",
  "processed": 1400
}

{
  "event": "employee.onboarded",
  "email": "new.hire@example.com",
  "name": "Priya Sharma",
  "startDate": "2026-11-02"
}

{
  "event": "employee.offboarded",
  "email": "leaver@example.com"
}

{
  "event": "leave.approved",
  "id": "lv_8812",
  "email": "dev@example.com",
  "from": "2026-11-12",
  "to": "2026-11-14",
  "kind": "leave"
}

{
  "event": "leave.cancelled",
  "id": "lv_8812"
}

{
  "event": "payroll.processed",
  "email": "dev@example.com",
  "period": "October 2026",
  "payslipUrl": "https://payroll.example.com/payslips/8812"
}

{
  "event": "command.task.create",
  "title": "Fix flaky login test",
  "priority": "high"
}

{
  "event": "message.posted",
  "channel": "releases",
  "text": "v2.4.0 is live in production"
}

{
  "event": "vulnerability.found",
  "id": "SNYK-JS-LODASH-1040724",
  "severity": "high",
  "title": "Prototype pollution in lodash",
  "package": "lodash@4.17.15",
  "cve": "CVE-2020-8203",
  "url": "https://security.example.com/advisories/1040724"
}

{
  "event": "vulnerability.resolved",
  "id": "SNYK-JS-LODASH-1040724"
}

{
  "event": "scan.completed",
  "critical": 0,
  "high": 1,
  "medium": 4,
  "low": 9
}

{
  "event": "agent.suggestion",
  "action": "create_task",
  "fields": {
    "title": "Add retry to payment webhook",
    "priority": "medium",
    "dueDate": "2026-11-20"
  },
  "reason": "Three timeouts in the last day"
}

{
  "event": "file.updated",
  "name": "Checkout flow v3",
  "url": "https://design.example.com/file/abc123",
  "taskKey": "TNC-1A2B3C"
}

Events we send

Set an HTTPS endpoint and the events you want in the partner console. When a room installs your app, its manager approves which of them that room sends; they can change it later. Events you add later reach a room only after its manager approves them.

Payloads carry ids, keys, titles, statuses, priorities, dates and links — never descriptions, comments, files, emails or end-to-end encrypted content. People appear as opaque user ids. Tasks your own app created carry data.origin.integrationId, so a two-way sync can ignore its own echoes.

POST https://your-endpoint.example.com/thinkncollab
X-TNC-Event: task.completed
X-TNC-Delivery-Id: evt_7f3c…          # the same on every retry: dedupe on it
X-TNC-Timestamp: 1791720000
X-TNC-Signature: v1=<hex HMAC-SHA256(partner secret, "<timestamp>.<raw body>")>
X-TNC-Api-Version: 2026-10-01
{
  "id": "evt_7f3c…",
  "type": "task.completed",
  "apiVersion": "2026-10-01",
  "occurredAt": "2026-10-11T09:20:00.000Z",
  "installationId": "6acb…",
  "roomId": "6ac9…",
  "app": "your-app-slug",
  "data": { "id": "…", "key": "T-6CUPC0", "title": "Ship dark mode", "status": "completed",
            "priority": "high", "dueDate": null, "assignees": ["6ac9…"], "url": "https://thinkncollab.com/app/rooms/…/tasks/…",
            "origin": null }
}

Verify the signature with your partner signing secret and reject timestamps more than five minutes old. Answer with any 2xx within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then given up. Answer 410 Gone to stop events for that room; after 25 failed deliveries in a day we pause sending to that room until its manager resumes it. Endpoints must be public HTTPS on port 443 or 8443; redirects are not followed.

Responses

Examples

cURL

curl -X POST "https://www.thinkncollab.com/api/v1/integrations/webhook/conn_your_connection_key" \
  -H "Content-Type: application/json" \
  -H "X-TNC-Secret: $TNC_SECRET" \
  -d '{"event":"test:run:completed","suiteName":"Regression","totalTests":50,"passedTests":50,"failedTests":0}'

GitHub Actions

- name: Report tests to ThinkNCollab
  if: always()
  run: |
    curl -sS -X POST "$TNC_WEBHOOK_URL" \
      -H "Content-Type: application/json" \
      -H "X-TNC-Secret: $TNC_SECRET" \
      -d "{\"event\":\"test:run:completed\",\"suiteName\":\"${{ github.workflow }}\",\"failedTests\":${{ steps.test.outputs.failed || 0 }}}"
  env:
    TNC_WEBHOOK_URL: ${{ secrets.TNC_WEBHOOK_URL }}
    TNC_SECRET: ${{ secrets.TNC_SECRET }}

Python

import json, os, hmac, hashlib, time, requests
body = json.dumps({"event": "payroll.disbursed", "employeeName": "Aarav", "action": "Salary paid"}, separators=(",", ":"), ensure_ascii=False)
sig = "sha256=" + hmac.new(os.environ["TNC_SECRET"].encode(), body.encode("utf-8"), hashlib.sha256).hexdigest()
requests.post(os.environ["TNC_WEBHOOK_URL"], data=body.encode("utf-8"), headers={
    "Content-Type": "application/json",
    "X-TNC-Signature": sig,
    "X-TNC-Timestamp": str(int(time.time() * 1000)),
}, timeout=10)

OAuth & Partner API

Apps that need to read or change room data use OAuth 2.0 (authorization code with PKCE) and call the Partner API with a short-lived bearer token. A token acts for exactly one installation: one app in one room, approved by that room's owner or a manager.

1. 1

   Register

   In the partner console, add your redirect URIs (https, matched exactly) and the scopes you need, then generate the client secret. It is shown once.

2. 2

   Authorize

   Send the user to /oauth/authorize with a PKCE challenge. They pick a room they manage and approve the scopes. Only verified apps can be connected.

3. 3

   Exchange

   Your server swaps the code (valid 10 minutes, single use) for an access token (1 hour) and a refresh token (30 days).

4. 4

   Call

   Send Authorization: Bearer <access token> to /api/partner/v1. Refresh before it expires; each refresh token works once.

Scopes

1. Send the user to authorize

import crypto from "node:crypto";
const verifier = crypto.randomBytes(32).toString("base64url");          // keep server side, per login
const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
const state = crypto.randomBytes(16).toString("base64url");             // check it on return
const url = new URL("https://www.thinkncollab.com/oauth/authorize");
url.search = new URLSearchParams({
  response_type: "code",
  client_id: process.env.TNC_CLIENT_ID,
  redirect_uri: "https://app.example.com/oauth/callback",
  scope: "tasks:read tasks:write",
  state,
  code_challenge: challenge,
  code_challenge_method: "S256",
});

On approval we redirect to your redirect URI with code and state; on denial with error=access_denied. If the client id or redirect URI is wrong we never redirect. PKCE with S256 is mandatory.

2. Exchange the code

curl -X POST "https://www.thinkncollab.com/oauth/token" \
  -u "$TNC_CLIENT_ID:$TNC_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d code_verifier="$VERIFIER"
# {"access_token":"tnc_at_…","token_type":"Bearer","expires_in":3600,
#  "refresh_token":"tnc_rt_…","scope":"tasks:read tasks:write","installation_id":"…"}

Authenticate with HTTP Basic (client_secret_basic) or client_id and client_secret in the body (client_secret_post), not both. Using a code twice revokes every token issued from it.

3. Refresh and revoke

curl -X POST "https://www.thinkncollab.com/oauth/token" -u "$TNC_CLIENT_ID:$TNC_CLIENT_SECRET" \
  -d grant_type=refresh_token -d refresh_token="$REFRESH_TOKEN"
curl -X POST "https://www.thinkncollab.com/oauth/revoke" -u "$TNC_CLIENT_ID:$TNC_CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN" -d token_type_hint=refresh_token

Every refresh returns a new refresh token; store it and drop the old one. Presenting an old refresh token again revokes the whole grant, so a leaked token can't be used quietly. Revoking a refresh token also revokes its access tokens. Uninstalling the app or a manager revoking the app's API access revokes everything for that room.

Partner API

Base URL https://www.thinkncollab.com/api/partner/v1. JSON in and out; send tokens only in the Authorization header.

curl "https://www.thinkncollab.com/api/partner/v1/tasks?limit=100" -H "Authorization: Bearer $ACCESS_TOKEN"
curl -X POST "https://www.thinkncollab.com/api/partner/v1/tasks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Follow up with design review","priority":"high","dueDate":"2026-11-02"}'

Tasks you create carry origin.integrationId in task events, so a two-way sync can skip its own echoes. Every call is recorded in an audit log (method, path, status and time; kept 30 days).