User guide
Integrations and AI agents
backendup's two outward doors: GitHub, which attaches proof of delivery to the work it belongs to, and the token API, which lets software - human's scripts and AI agents alike - work the backlog as a teammate. Both doors lead into the same records your team already uses; neither opens a privileged entrance.
Connecting GitHub
Organization Settings has a GitHub App section with an Install GitHub App button - the hosted path, which lets mapped repositories attach pull requests "without a pasted webhook secret". Once installed it shows the installation it is connected as, and can be disconnected there. (If the section says the App is not configured on this server, the per-project door below still works.)
The link to your code is then made per project: the project's edit page maps it to a GitHub
repository as owner/name - one project per repository per organization, so a
webhook event can never be ambiguous about which project owns it. On the project page, a
GitHub webhook panel shows the webhook URL to paste into repository
settings and lets you rotate its signing secret - the self-hosted-GitHub path.
How a pull request finds its work item
By reference, not by guesswork: when GitHub reports a pull request, backendup reads work-item
references (like ENG-1) from the PR's title, body
and branch name, and attaches the PR as a delivery link to each referenced
item in that project. A merged PR records its merge commit; open, merged and closed states
are tracked on the link itself. Nothing is invented - a PR that references nothing links to
nothing, which is why teams settle into putting the reference in the branch name.
Status moves from GitHub are opt-in per project mapping, and even when enabled they walk the organization's transition matrix like any human move would - the integration has no authority to break workflow rules.
Delivery evidence on the item
The Delivery evidence panel of a work item collects commits, pull requests and compare URLs from the webhook, from the API, and by hand: pick a Type, paste a URL, and it is on the record beside the discussion. Links can be removed again; the project's delivery-evidence setting decides whether the panel shows automatically once a repository is mapped, always, or never.
API tokens: two doors
Organization Settings → API tokens says it in one line: "Personal tokens act as you. Service-account tokens act as the bot."
- Create a personal token - for your own scripts. Everything it does is audited under your name and can only do what you could do.
- Service accounts → Manage - the bot page: create a bot with a username and a display name, then issue tokens that act as it. The list shows each token's prefix, expiry, last use and status (Active / Expired / Revoked), and revoking one is a button.
A service account is a member of the organization in the real sense - it holds Member access (never Owner) so its work is attributed and revocable - but it is a door, not a person: it has no email, an unusable password, and cannot sign in to the website. If a bot's token leaks, you revoke the token or retire the account without touching any human's access.
Channel webhooks
A channel webhook lets an outside system - CI, monitoring, a build farm - write into one channel and nothing else. Open the channel in Collaboration, then Webhooks in its header, and Create webhook. Two things happen at once: the channel gets a bot member named after the webhook, and you are shown a URL and a secret once. Copy them there; the secret is never rendered again.
- Posting -
POSTthe URL with the headerX-Backendup-Webhook-Secretand a JSON body{"text": "Build 42 is green."}. Add"thread": <message id>to reply under an existing message. The answer is201with the new message id. - Identity - the message appears as the bot, wearing the Bot badge and the webhook's name as its credential. There is no key in the payload that renames the author or supplies an avatar: identity is the account, never a decoration.
- One channel, always - a webhook cannot be re-pointed. Need another channel? Create another webhook there.
- Limits - a webhook may post 30 messages a minute, and its bot stays under the same per-person posting budget as anyone else. Over either limit the door answers
429with aRetry-Afterheader rather than dropping the message silently. - Rotate, revoke, delete - Rotate replaces the secret on the spot and shows the new one once; the old value stops working immediately while the webhook's identity and the channel's history stay intact. Revoke kills the secret and keeps the configuration, so a later rotate re-arms it. Delete archives the configuration and freezes the bot, which also frees the seat it held; the messages it already wrote stay in the channel.
Who may arm one. Organization Settings → Service accounts carries the ceiling - Owners and admins by default, and Nobody turns channel webhooks off for the whole organization. A channel manager can tighten that ceiling for their own channel in the same Webhooks panel; no channel can widen it. Every create, rotate, revoke, delete, and permission change is written to an audit trail that outlives the secret.
Event subscriptions
A channel webhook lets an outside system write into a channel. An event subscription is the other direction: it signs one channel's messages out to an endpoint you run. Open the channel, then Subscriptions in its header, and supply a name, a target URL and the event types you want. You are shown a signing secret once; copy it there, because it is never rendered again.
- Events -
message.posted,message.editedandmessage.deleted. A deletion carries a tombstone and never the body that was removed, because the room stopped showing it for a reason. - Delivery - each event is
POSTed to your target as JSON carrying the Standard Webhooks headerswebhook-id,webhook-timestampandwebhook-signature, so an off-the-shelf verifier library works against it unchanged. - Verifying - base64 the
HMAC-SHA256of{id}.{timestamp}.{body}under the secret and compare it with eachv1,term of the signature header. Compare against the bytes you received rather than a re-serialization of them: key order and spacing are part of what was signed. Reject a timestamp more than a few minutes from now, and usewebhook-idas your idempotency key - every retry and every manual resend reuses it verbatim, so a duplicate is recognizable instead of being applied twice. - Retries - an attempt that does not answer
2xxwithin 10 seconds is retried after 1, 2, 4 and then 8 minutes, doubling to an hour cap, for five attempts. After that the delivery dead-letters and stays readable in the panel with its reason, and Resend re-arms it under the samewebhook-id. A4xxother than408or429is not retried at all: your endpoint said it will never accept this, so repeating it is noise rather than patience. - Rotate, disable, delete - Rotate shows a new secret once and keeps signing with the old one for 24 hours, so a receiver mid-rollout never breaks and a retry already in flight still verifies. Disable stops delivery immediately and can be re-armed; it is the lever to pull during an incident. Delete archives the configuration while the delivery history stays readable, because "what did we send, and to where" is the question asked afterwards.
- Privacy floor - a subscription reads as its own bot member of that one channel, so it can never carry more than that bot could already see there. Forwarded-message provenance is never included: a forward into this channel does not disclose the private channel, project or roster it came from. Loopback, private, link-local and reserved targets are refused when armed and re-checked on every attempt, so re-pointing a hostname at an internal address does not become a way in.
- No echo loops - a message written by a channel webhook's own bot emits nothing, so an integration that receives an event and posts back into the channel cannot start a loop.
Published test vectors. These let you prove a verifier before pointing it at
live traffic. The suite asserts the same values, so a receiver that verifies these verifies
production deliveries too. The signature covers webhook-id, a dot,
webhook-timestamp, a dot, and the body exactly as written here:
secret whsec_backendup_test_vector_only
webhook-id bup_evt_01J8ZK0TESTVECTOR0000000
webhook-timestamp 1763136000
body {"conversation_id":"bup_conv_01J8ZK0TESTVECTOR0000","id":"bup_evt_01J8ZK0TESTVECTOR0000000","message_id":"bup_msg_01J8ZK0TESTVECTOR00000","type":"message.posted"}
webhook-signature v1,iRVTCq5c+4Pg4OqpybRS/3MAPu76MW2zFDzm9G4nNoc=
Inside a rotation the header carries two space-separated terms, one per key. With
whsec_backendup_test_vector_rotated_out as the key being retired, the same
timestamp and body also verify under:
v1,iRVTCq5c+4Pg4OqpybRS/3MAPu76MW2zFDzm9G4nNoc= v1,8bL/XToTE/Ru3A5mW5Ty+LGcREeEUkmFjMKwyCFJkFU=
Accept the delivery if any term matches a key you currently hold. Checking only the first term is the mistake that breaks a receiver during the 24-hour window.
Who may arm one. On an organization-policy channel, which every active member
can read, arming an export is an organization-wide decision and needs an owner or an admin. On
a named-membership channel the roster is the audience, so holding a seat in it is enough. A
caller below that bar is answered 404 rather than 403 and sees no
panel at all, so these routes cannot be used to discover that a channel exports its traffic.
Working with AI agents
The pitch on the front page - a story claimed, commented and completed by an AI agent, assigned like any teammate - is literally that:
-
Make the bot a teammate.
Create the service account, then add it to the project like any member - in the roster, it can be assigned work. -
Point a runner at the API.
Issue the bot a token and give it to your agent runner. The API reference is written for exactly this reader: find the next claimable item, claim it, work, report. The sample agent skill packages the same contract as a ready-to-install SKILL.md for coding agents. -
Watch it work in public.
A claim moves the item to In Progress atomically and auditable; arun_idlets a crashed runner resume its exact item instead of grabbing a new one. Progress lands in the item's discussion as markdown comments - the same thread your humans use. -
Judge it by the same evidence.
Agents attach commit and pull-request delivery links and move status through the same transition matrix. Nothing distinguishes a well-behaved agent's completed story from a human's - which is the point.
The guardrails are the workflow's, not new ones: agents see only organizations and projects their membership reaches, every call is audited to the token owner, and automation rules react to an agent's status changes exactly as they react to a person's.
Discussion notifications leave the product through email - immediately or in a scheduled digest, chosen per person in profile settings. The doors are described in Collaboration's notification section; nothing here needs configuration by an admin.