Tickets where your team already works

01Concepts

Connection

A workspace-level credential to one destination: one Jira site, one Slack webhook, the GitHub App installation, one webhook secret. Encrypted at rest; many channels can share it.

Channel

One destination target on one repo, optionally one branch, through a connection: "Jira project DEPS for acme/web, main, P0–P2, on created, reopened and verified".

Routing rules

Which tickets a channel carries (priorities, kinds, risk, ready only) and on which events it speaks (created, reopened, verified, status changes, agent notes, comments).

Link

The external item that mirrors one ticket on one channel: issue #412, DEPS-12, a Discord message. One per channel and ticket, never two.

Delivery

One outbound or inbound unit of work with an idempotency key, attempts, status, latency and a redacted error. The delivery log is the list of these.

One-way or two-way

Chat tools and email get cards and mail. Trackers and the webhook also talk back: their comments are mirrored into the discussion and their state changes are noted on the ticket.

Routing rules carry priorities (the wizard offers Red, Amber and Green presets over them), ticket kinds, risk, "ready only" and the triggers. Branch scope is the channel's: leave it empty for every tracked branch, or make one channel per branch. Trackers that support labels get pinwise and the ticket kind.

02The agent footer and MCP

MCP stays the primary path. Every mirror ends with a footer aimed at coding agents: the ticket id, the link, and the instruction to update the ticket over the pinwise MCP, not on the mirror. Trackers and the webhook payload get the long form; chat cards carry the two-line short form.

---
**pinwise TDB-0012** · https://pinwise.dev/app/tickets/01JB…
AI agents: use the pinwise MCP (https://pinwise.dev/docs/mcp) to start, update and complete
this ticket on pinwise.dev; this copy is a mirror and closes only when a pinwise rescan verifies
the upgrade. `ticket_id: 01JB…`
<!-- pinwise:ticket=01JB… channel=01JC… -->

pinwise TDB-0012 · <link> · agents: update it over the pinwise MCP (ticket_id 01JB…)

The HTML comment is the machine marker. Searchable destinations are checked for it before an item is created, so a lost link never duplicates an item, and inbound comments carrying it are dropped as echoes. Over MCP,get_ticket and list_tickets list a ticket's mirrors and its external state; agents update the ticket here and call request_rescan when they are done.

03State rules

An external change never closes a pinwise ticket. The badge says "closed in Jira, awaiting verification"; the green tick needs a pinwise rescan that finds the upgrade in the lockfile.

Outbound: pinwise status → the mirror

Defaults per destination; a channel's state map can override any row. Tickets in stale leave the mirror alone.

Inbound: what a change over there does here

Closed, done or resolved over there

The ticket is marked "closed externally, awaiting verification" and stays open. With "rescan when they close an item" on, the home branch is rescanned; the ticket closes as closed_verified only if the lockfile reached the target. Otherwise a comment goes back on the mirror saying the upgrade is not in the lockfile yet.

Canceled or won’t do

Treated as closed externally: the same badge, the same rescan. It never sets wontfix on its own.

Reopened after we closed it

Noted as "reopened externally" on the ticket. No status change: a verified close is evidence. You can reopen from the board as always.

Moved to in progress

Shown in the activity feed. No status change: leases belong to agents.

A comment by someone who is not pinwise

Mirrored into the discussion as "Jane via Jira", with follows and notifications as for a web comment. Our own comments and anything carrying the footer marker are dropped as echoes.

The item is deleted

The link is removed. The next matching event creates a fresh mirror if the channel sends on created.

"Closed externally" clears when the ticket's status changes on our side: verified, reopened by a rescan or won't fix. State loops cannot happen, because inbound never changes the ticket's status.

04Plans

Channels count per workspace while active; paused ones do not. Two-way sync is part of Studio and up: on a lower plan a tracker channel is outbound only. See pricing.

05Setup guides

Settings → Ticket channels → Add channel walks you through destination, connect, target, rules and a test. Every credential is stored encrypted and never shown again; what each destination needs is below.

06Webhook contract

pinwise POSTs JSON to your URL with Content-Type: application/json and three headers. The body is payload version 1: fields are added, never renamed or removed; a breaking change would ship as version 2 alongside.

Events

ping

Sent by "Send a test" and when the channel is created. ticket_id and status are null.

ticket.created

A ticket matched the rules for the first time. Carries the full ticket and the footer.

ticket.updated

The ticket text or priority changed. Carries the full ticket and the footer.

ticket.state_changed

The pinwise status moved (verified, reopened, wontfix, …). status is the new one.

ticket.comment

An agent note or a human comment, when the channel sends them. comment has body, author and via.

Payload

{
  "version": 1,
  "id": "01JDQ4Z6M8R3V3F5K1S0C4YJ7P",
  "event": "ticket.created",
  "sent_at": "2026-10-29T10:00:00.000Z",
  "channel_id": "01JCX2H4N9T6Q7W8E1R2T3Y4U5",
  "ticket_id": "01JB7G5V2K4M6N8P0Q2R4S6T8V",
  "status": "open",
  "ticket": {
    "id": "01JB7G5V2K4M6N8P0Q2R4S6T8V",
    "display_id": "TDB-0012",
    "number": 12,
    "title": "Upgrade lodash to 4.17.21 (CVE-2021-23337)",
    "body_md": "## Target and why\n\nlodash 4.17.15 → 4.17.21 …",
    "status": "open",
    "priority": 0,
    "kind": "cve",
    "risk": "low",
    "package": "lodash",
    "ecosystem": "npm",
    "from_version": "4.17.15",
    "target_version": "4.17.21",
    "repo": "acme/web",
    "branch": "main",
    "url": "https://pinwise.dev/app/tickets/01JB7G5V2K4M6N8P0Q2R4S6T8V",
    "created_at": "2026-10-29T09:58:41.000Z",
    "updated_at": "2026-10-29T09:58:41.000Z"
  },
  "footer": "---\n**pinwise TDB-0012** · https://pinwise.dev/app/tickets/01JB…\nAI agents: use the pinwise MCP (https://pinwise.dev/docs/mcp) to start, update and complete\nthis ticket on pinwise.dev; this copy is a mirror and closes only when a pinwise rescan verifies\nthe upgrade. `ticket_id: 01JB…`\n<!-- pinwise:ticket=01JB… channel=01JC… -->",
  "external_id": null,
  "comment": null
}

ticket and footer are set for ticket.created andticket.updated; status and ticket_id for every event butping; comment for ticket.comment. external_id is your id once you have answered a create with one, else the pinwise ticket id.

What your receiver must do

Answer any 2xx within 15 seconds

Do the work after answering; a slow receiver times out and is retried.

Reply to ticket.created with your id

Optional JSON {id, key, url}; pinwise then uses your id as external_id. Otherwise the pinwise ticket id is used.

401 or 403 breaks the channel

Means the secret is wrong. So do 404 and 410. 429 with Retry-After and 5xx are retried with backoff.

https on port 443, a hostname, no redirects

IP addresses, private hosts and redirects are refused, on every delivery, not only when you save.

{
  "id": "task_8812",
  "key": "OPS-77",
  "url": "https://tasks.example.com/OPS-77"
}

Calling back (two-way)

When two-way sync is on, the channel gets a callback URL and an inbound secret, shown once. Send one message per request, signed the way we sign deliveries.

{"version":1,"id":"evt-1041","type":"state","external_id":"task_8812","state":"Done","actor":"jane"}
{"version":1,"id":"evt-1042","type":"comment","external_id":"task_8812","comment_id":"c-77","body":"Looks good on staging","author":"jane"}

Sign with the inbound secret

Same scheme as our deliveries: X-Pinwise-Signature over "<t>.<raw body>". The callback URL and the secret are shown once when two-way sync is turned on.

One message per request

type "state" with your own state name (add kind when the name is unusual) or type "comment" with comment_id, body and author.

id is yours and unique

A repeated id answers 200 and is ignored. Success answers 202; a bad signature or a timestamp older than 5 minutes answers 401.

A close never closes the ticket

An external change never closes a pinwise ticket. The badge says "closed in Jira, awaiting verification"; the green tick needs a pinwise rescan that finds the upgrade in the lockfile.

07Verify signatures

Always verify against the raw body bytes, before parsing JSON, with a constant-time compare, and reject timestamps older than five minutes. The same check works for callbacks pinwise receives: swap in the inbound secret.

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

export function verifyPinwise(rawBody, header, secret, toleranceSeconds = 300) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
  if (!match) return false;
  const [, t, mac] = match;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(mac, 'hex'), Buffer.from(expected, 'hex'));
}

// Express: keep the raw body.
app.post('/pinwise', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyPinwise(req.body, req.get('X-Pinwise-Signature'), process.env.PINWISE_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // dedupe on event.id, then handle event.event
  res.sendStatus(204);
});

import hashlib, hmac, re, time

SIG = re.compile(r"^t=(\d+),v1=([0-9a-f]{64})$")

def verify_pinwise(raw_body: bytes, header: str | None, secret: str, tolerance: int = 300) -> bool:
    m = SIG.match(header or "")
    if not m:
        return False
    t, mac = m.group(1), m.group(2)
    if abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, expected)

# Flask: request.get_data() is the raw body.
# if not verify_pinwise(request.get_data(), request.headers.get("X-Pinwise-Signature"), SECRET): abort(401)

Signing a callback

import { createHmac } from 'node:crypto';

export async function sendCallback(message) {
  const body = JSON.stringify(message);
  const t = Math.floor(Date.now() / 1000);
  const v1 = createHmac('sha256', process.env.PINWISE_INBOUND_SECRET).update(`${t}.${body}`).digest('hex');
  return fetch(process.env.PINWISE_CALLBACK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Pinwise-Signature': `t=${t},v1=${v1}` },
    body,
  });
}

08Zapier and Make

The generic webhook is how pinwise reaches Asana, Trello, Notion and everything else. Both recipes verify the signature first, then create the item with the title, the link and the footer.

Zapier

1. Trigger: Webhooks by Zapier → Catch Raw Hook. Paste the hook URL into the pinwise channel and press Send a test; it delivers a ping.
2. Action: Code by Zapier → Run JavaScript. Input fields: raw = Raw Body, sig = Headers Http X Pinwise Signature, secret = your signing secret. Paste the code below.
3. Filter by Zapier. Continue only if ok is true and event is ticket.created.
4. Action: create the item in your tool. Asana, Trello, Notion, …: title as the name, url plus footer in the description so coding agents can find the pinwise ticket.
5. Calling back (optional). A second Code step builds and signs the message with the callback helper, then Webhooks by Zapier → Custom Request POSTs it with the X-Pinwise-Signature header.

const crypto = require('crypto');
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(inputData.sig || '');
const ok = !!m && Math.abs(Date.now() / 1000 - Number(m[1])) < 300 &&
  crypto.timingSafeEqual(Buffer.from(m[2], 'hex'),
    crypto.createHmac('sha256', inputData.secret).update(`${m[1]}.${inputData.raw}`).digest());
const event = ok ? JSON.parse(inputData.raw) : {};
return { ok, event: event.event, title: event.ticket?.title, url: event.ticket?.url, footer: event.footer };

Make

1. Webhooks → Custom webhook. Under advanced settings enable Get request headers and JSON pass-through, so the raw body is available.
2. Set variable: expected. expected = sha256(t + "." + body; "hex"; secret), where t is the part of the x-pinwise-signature header between t= and the comma (get(split(header; ","); 1) and replace), body is the raw value and the third argument makes Make compute the HMAC.verify in your scenario
3. Filter. Continue only when expected equals the v1= part and t is within 300 seconds of timestamp. Make’s compare is not constant time: keep the signing secret long and random.verify in your scenario
4. JSON → Parse JSON. Parse the body, then route on event.

The Make HMAC step is written from Make's function reference and has not been run end to end by us; check it against a test delivery before trusting it.

09Troubleshooting

Health

The delivery log

Every channel page lists its deliveries, outbound and inbound, with attempts, latency, the response status and a redacted error. Delivered and skipped rows are kept for 90 days, dead ones for 180.

queued

Waiting for the consumer; usually seconds.

delivering

In flight. Anything stuck here for 30 minutes is re-queued by the hourly catch-up.

delivered

The destination answered 2xx; the link and the health chip are updated.

failed

Failed and scheduled to retry; the row shows the next attempt.

dead

Out of attempts, or an error that never retries (auth, invalid target). Owners can retry by hand.

skipped

Nothing to do: a duplicate, an unknown inbound event, or the channel was paused.

Retries

Network errors, timeouts, 5xx and 429 are retried after 30 s, 2 min, 10 min, 1 h, 6 h, five attempts in all; a 429 with Retry-After waits that long (at most an hour) without counting as an attempt. Auth and invalid-target errors never retry: they stop the channel at once. An hourly catch-up re-queues anything stuck in flight and dispatches for workspaces whose nudge was missed.

Common questions

The channel shows "stopped"

Open the channel: the health card names the error kind. Auth means the token or OAuth grant was revoked (reconnect); invalid target means the project, repo or webhook URL is gone (edit the target); after five dead deliveries the last error is shown. Fix the destination, then press Test to resume.

A ticket was pushed twice

It should not be: there is one link per channel and ticket, and trackers are searched for the footer marker before an item is created. If you deleted the item over there, the next matching event recreates it. Send the delivery id from the log to support if you see two live items.

They closed the item but the ticket is still open

By design. The badge says "closed in Jira, awaiting verification" (or GitHub, Linear, …). Turn on "rescan when they close an item", or request a rescan from the ticket or over MCP. The ticket closes only once the lockfile shows the target.

Nothing arrives

Check the rules: the channel only speaks for the priorities, kinds, risks and triggers you picked, and only for its repo and branch. "Send a test" in the wizard posts a sample without touching the rules; the log says whether the destination answered.

You got "Your Jira channel for acme/web stopped working"

One mail per break, sent to the workspace owners, with the error kind and what to do. You get "is working again" once it recovers. Channels paused by a plan change get the same mail as paused repos.

Webhook deliveries answer 401

The signing secret you verify with is not the one shown when the channel was created. Rotate it from the channel page and update your receiver; a 401 or 403 from your side breaks the channel at once.

Email recipients never got the mail

External addresses stay pending until the mailbox owner uses the confirm link; workspace members are trusted. Each address gets at most 20 mails an hour, digest and instant together, and can unsubscribe with one click.