Docs/Reference
Webhooks
We post each change to your server as it happens, signed, retried, and safe to receive twice.
Add an endpoint
On Settings › API, webhooks and MCP, or through the API with POST /v1/webhooks. Give it a URL and the events it wants.
- Choose events. An empty list means every type we send, except the high-volume ones marked opt-in, which have to be named.
- Store the signing secret. It's shown twice and never again: when you create the endpoint, and when you rotate it. Every other response, including the list and the edit, leaves it out. If you lose it, rotate it. Your receiver will treat deliveries as unsigned until it has the new secret.
- Answer fast. Return a 2xx within 10 seconds and do slow work afterwards.
A webhook endpoint counts as an integration: Plus includes one, Pro has no limit. We do not follow redirects, and an endpoint that answers one is recorded as a failure with the address it pointed at.
What arrives
A POST with a JSON body and three headers you can rely on: X-Heedpost-Signature, X-Heedpost-Event (the type) and the user agent Heedpost-Webhooks/1.
{
"id": "0192f3c4-…", // the event's own id: dedupe on it
"type": "post.status_changed",
"created_at": "2026-10-17T09:12:44.512+00:00",
"workspace": { "id": "…", "slug": "acme" },
"actor": { "id": "…", "name": "Dana Whitfield" }, // null when nobody acted
"subject": { "type": "post", "id": "…" },
"data": { "from": "review", "to": "planned",
"from_name": "Under review", "to_name": "Planned" }
}data carries named keys only, listed per type in the catalog below, so a payload that grows a field never grows a leak. No email address is ever in a body: a member's id goes instead, which an API key can resolve.
Verify the signature
X-Heedpost-Signature is an HMAC-SHA256 over the timestamp and the raw body:
X-Heedpost-Signature: ts=1724500000;h1=<hex>
digest = hmac_sha256(secret, f"{ts}:{raw_body}")Check the timestamp as well as the signature. The timestamp is part of what's signed, so nobody can change it without breaking the signature. Without a time limit, though, a copied request would stay valid forever. The examples allow five minutes.
Verify against the raw bytes. Re-serialising the JSON first produces a different document and a signature that never matches.
import hmac, hashlib, time
def verify(secret: str, header: str, raw_body: bytes, window: int = 300) -> bool:
"""header is X-Heedpost-Signature: ts=<unix>;h1=<hex>"""
parts = dict(p.split("=", 1) for p in header.split(";") if "=" in p)
ts, sent = parts.get("ts", ""), parts.get("h1", "")
if not ts.isdigit() or abs(time.time() - int(ts)) > window:
return False # stale, or from the future
signed = ts.encode() + b":" + raw_body # the raw bytes, never re-serialised JSON
digest = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(digest, sent)import crypto from "node:crypto"; // header is X-Heedpost-Signature: ts=<unix>;h1=<hex> export function verify(secret, header, rawBody, windowSeconds = 300) { const parts = Object.fromEntries(header.split(";").map((p) => p.split("=", 2))); const ts = Number(parts.ts); if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > windowSeconds) return false; const digest = crypto.createHmac("sha256", secret) .update(`${parts.ts}:`).update(rawBody) // rawBody is a Buffer of the bytes received .digest(); const sent = Buffer.from(parts.h1 ?? "", "hex"); return sent.length === digest.length && crypto.timingSafeEqual(sent, digest); }
Retries and duplicates
Timeout10 seconds per attempt.
Retries8 attempts for a 5xx or a timeout, each wait twice the last.
DuplicatesDelivery is at least once. A retried delivery carries the same event
id, so dedupe on it.ResendingFrom the delivery log on Settings · API, webhooks and MCP, 60 an hour.
Event catalog
110 types in 23 families, each with the keys its data carries. vote.added is the one opt-in type: it carries the new total and never says who voted.
api key 2
api_key.createdNothing in
data. The type and subject say it all.api_key.revokedNothing in
data. The type and subject say it all.
board 5
board.createdslug,nameboard.deletedslug,nameboard.reorderedorderboard.restoredslug,nameboard.updatedname,was
board category 5
board_category.createdname,board_idboard_category.deletedname,board_idboard_category.reorderedorder,board_idboard_category.restoredname,board_idboard_category.updatedname,was,board_id
board field 5
board_field.createdkey,label,type,board_idboard_field.deletedkey,label,board_idboard_field.reorderedorder,board_idboard_field.restoredkey,label,board_idboard_field.updatedkey,label,was,board_id
changelog 5
changelog.createdslug,titlechangelog.deletedslugchangelog.publishedslug,title,postschangelog.restoredslugchangelog.updatedslug,changed
changelog label 4
changelog_label.createdname,colorchangelog_label.deletednamechangelog_label.restorednamechangelog_label.updatedname,was,changed
clickup 6
clickup.connectedNothing in
data. The type and subject say it all.clickup.disconnectedNothing in
data. The type and subject say it all.clickup.issue_linkedissue,createdclickup.issue_unlinkedissueclickup.reconnectedNothing in
data. The type and subject say it all.clickup.updatedNothing in
data. The type and subject say it all.
comment 4
comment.createdpost_id,is_internalcomment.deletedpost_idcomment.restoredpost_idcomment.updatedpost_id
custom domain 4
custom_domain.addedhostnamecustom_domain.primary_changedhostnamecustom_domain.removedhostnamecustom_domain.verifiedhostname
digest 1
digest.sentposts,shipped
github 6
github.connectedNothing in
data. The type and subject say it all.github.disconnectedNothing in
data. The type and subject say it all.github.issue_linkedissue,createdgithub.issue_unlinkedissuegithub.reconnectedNothing in
data. The type and subject say it all.github.updatedNothing in
data. The type and subject say it all.
import 3
import.failedprovider,stateimport.finishedprovider,state,boards,posts,comments,votes,people,user_segments,releases,imagesimport.startedprovider
jira 6
jira.connectedNothing in
data. The type and subject say it all.jira.disconnectedNothing in
data. The type and subject say it all.jira.issue_linkedissue,createdjira.issue_unlinkedissuejira.reconnectedNothing in
data. The type and subject say it all.jira.updatedNothing in
data. The type and subject say it all.
linear 6
linear.connectedNothing in
data. The type and subject say it all.linear.disconnectedNothing in
data. The type and subject say it all.linear.issue_linkedissue,createdlinear.issue_unlinkedissuelinear.reconnectedNothing in
data. The type and subject say it all.linear.updatedNothing in
data. The type and subject say it all.
member 5
member.invite_revokedrolemember.invitedrolemember.joinedrolemember.removeduser_id,rolemember.role_changedfrom,to
post 16
post.board_changedfrom,to,from_name,to_name,from_slug,to_slug,category_clearedpost.category_changedfrom,to,from_name,to_namepost.comments_lockednotepost.comments_unlockedNothing in
data. The type and subject say it all.post.createdtitle,board_id,is_privatepost.deletedNothing in
data. The type and subject say it all.post.mergedinto,title,votes,comments,shared_voterspost.pinnedNothing in
data. The type and subject say it all.post.plan_changedowner_id,target_date,waspost.privacy_changedis_privatepost.restoredNothing in
data. The type and subject say it all.post.status_changedfrom,to,from_name,to_namepost.tags_changedadded,removedpost.unmergedfrompost.unpinnedNothing in
data. The type and subject say it all.post.updatedtitle,by_author
slack 4
slack.connectedNothing in
data. The type and subject say it all.slack.disconnectedNothing in
data. The type and subject say it all.slack.reconnectedNothing in
data. The type and subject say it all.slack.updatedNothing in
data. The type and subject say it all.
sso 4
sso.configuredNothing in
data. The type and subject say it all.sso.disabledNothing in
data. The type and subject say it all.sso.enabledNothing in
data. The type and subject say it all.sso.rotatedNothing in
data. The type and subject say it all.
status 5
status.createdname,kindstatus.deletedname,moved,moved_tostatus.reorderedNothing in
data. The type and subject say it all.status.restorednamestatus.updatedname,kind,was
tag 4
tag.creatednametag.deletednametag.restorednametag.updatedname,was,changed
tenant 5
tenant.closednametenant.createdslug,nametenant.plan_changedfrom,to,whytenant.reopenedname,closed_attenant.updatedname,was
vote 1
vote.addedopt-incount
webhook 4
webhook.addedurl,event_typeswebhook.removedurlwebhook.rotatedurlwebhook.updatedurl,was