Webhooks

Register endpoints under /orgs/{orgId}/webhooks (list, create, update, test, rotate-secret, deliveries, redeliver, requeue-failed). Each request carries x-goodqa-signature: t=<unix>,v1=<hex> where v1 is HMAC-SHA256 of "<t>.<rawBody>" with your secret, plus x-goodqa-event, x-goodqa-delivery (the same id on every retry: dedupe on it) and user agent GoodQA-Webhooks/1. Reject a timestamp more than 300 s from now. While a secret is being rotated the header carries one v1= per accepted secret; accept any. Failed deliveries are retried with exponential backoff (30 s doubling, capped at 1 h) up to 6 attempts, then kept as failed and can be redelivered. Redirects are never followed.

Events:

• chat.dm.message.created
• chat.message.created
• chat.mention.created
• issue.comment.created
• crm.record.created
• crm.record.updated
• crm.record.archived
• crm.flags.changed
• crm.tags.changed
• crm.relationship.created
• crm.relationship.ended
• crm.lifecycle.enrolled
• crm.lifecycle.transitioned
• crm.lifecycle.sla_breached

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the exact bytes received (do not re-serialise). secret: your whsec_... value.
export function verify(secret, headers, rawBody) {
  const header = headers['x-goodqa-signature'] ?? '';
  const parts = header.split(',').map((p) => p.split('='));
  const t = Number(parts.find(([k]) => k === 't')?.[1]);
  const candidates = parts.filter(([k]) => k === 'v1').map(([, v]) => v); // several during secret rotation
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  return candidates.some((c) => {
    const got = Buffer.from(c, 'hex');
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}
// Dedupe on headers['x-goodqa-delivery']: it is identical on every retry of one delivery.

import hashlib, hmac, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    header = headers.get("x-goodqa-signature", "")
    parts = [p.split("=", 1) for p in header.split(",") if "=" in p]
    t = next((v for k, v in parts if k == "t"), None)
    if t is None or not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(v, expected) for k, v in parts if k == "v1")  # several during rotation
# Dedupe on headers["x-goodqa-delivery"]: it is identical on every retry of one delivery.

Key scopes

A key names zero or more families. A key naming none reaches every route an API key may use except the explicit-only set; a key naming some is limited to those. GET /v1/capabilities returns the effective list as caller.apiKey.scopes. Families:

• mail
• roadmap_suggestions
• work
• issue_types
• command_center
• work_dashboard
• orgs
• projects
• issues
• testing
• uploads
• ai
• github
• decisions
• mcp
• agent_memory
• project_memory
• context_memory
• vault
• artifacts
• documents
• surface
• notifications
• agents
• chat
• stats
• marketing
• experience_reviews
• deploy
• invites
• cms
• billboard
• crm
• runner
• data
• agent_knowledge
• memory
• outreach
• agent_launch
• notes_to_self
• usage
• usage:write
• machines
• escalation

Missions, step results and test plans

Missions and test plans need the testing family. Step results are written with PUT /missions/{missionId}/step-results. An API key is refused (403) on a mission whose recordingPolicy is required, and recording sessions are always started by a person; set the policy to optional for automation. Errors are catalogued at GET /v1/meta/errors.

Verification ledger

GET /issues/{issueId}/verifications lists the hash-chained attestations that a mission verified an issue; POST to the same path appends one. Each entry is chained to the one before it, so an edited or removed entry breaks verification of the rows after it. The same issue and project visibility rules as the issue apply; an issue you cannot see answers 404.

Issue links and pull requests

GET|POST /issues/{issueId}/links reads and adds links between issues; POST /issues/{issueId}/pull-requests attaches a GitHub pull request and GET /issues/{issueId}/fix-pull-requests lists the ones that fix it. Exact bodies and responses are in the endpoint reference below.

Idempotency-Key

Send Idempotency-Key on these create routes. The same key and body within 24 hours replays the first result; the same key with a different body is refused; keys are per caller. Routes:

• POST /v1/orgs/:p/artifacts
• POST /v1/artifacts/:p/versions
• POST /v1/artifacts/:p/links
• POST /v1/projects/:p/issues
• POST /v1/issues/:p/comments
• POST /v1/issues/:p/links
• POST /v1/issues/:p/dependencies
• POST /v1/orgs/:p/crm/contacts
• POST /v1/orgs/:p/crm/companies
• POST /v1/orgs/:p/crm/records/:p/:p/notes
• POST /v1/orgs/:p/dm/:p
• POST /v1/projects/:p/test-plans
• POST /v1/orgs/:p/agent-knowledge/:p/supersede

Changelog

GET /v1/changelog returns what shipped per release, machine-readable, with an ETag and a since filter. The MCP tool changelog returns the same.

CLI commands

The goodqa CLI reads GOODQA_API_KEY and prints JSON. The MCP tool list is above in the MCP section. Commands:

• goodqa whoami
• goodqa capabilities
• goodqa issues list
• goodqa issues get
• goodqa issues create
• goodqa issues comment
• goodqa issues status
• goodqa dm send
• goodqa dm inbox
• goodqa events listen
• goodqa knowledge search
• goodqa knowledge write
• goodqa knowledge purge
• goodqa followups list
• goodqa followups create
• goodqa followups transition
• goodqa secret-request create
• goodqa secret-request status
• goodqa secret-request list
• goodqa mcp config print
• goodqa product search
• goodqa product describe
• goodqa product whats-new
• goodqa product how-do-i
• goodqa help
• goodqa version