Support bridge
Keep your app's own ticket system. Each new ticket becomes a task in the dev box that maintains the app, and the agent you start there reads the thread, investigates with your logs and code, and sends the reply you approve.
How it works
- Your app posts a signed event when a ticket arrives or the customer writes again. HostStack files a task in the project’s dev box and tells your notification channels. Nothing runs until somebody presses Start.
- The task carries the ticket and the customer’s message, fenced and labelled as untrusted text, plus how to work it: read the thread, investigate, note the findings on the ticket, draft a reply.
- With a bridge URL, the agent reads the live thread, adds internal notes and sends the reply through your app — so it reaches the customer the way every other staff reply does, and your helpdesk stays the record.
- A customer writing again on a finished task reopens it. Resolving the ticket in your app closes a task nobody started.
Set it up
Create the bridge
On the service’s Support tab, press Create support bridge. HostStack writes
HOSTSTACK_SUPPORT_BRIDGE_IDandHOSTSTACK_SUPPORT_BRIDGE_SECRETinto the service’s env vars; they apply on the next deploy. An agent in your dev box can do this withcreate_support_bridge.Report tickets
Call
sendSupportEventwhere your app already notifies staff. Any language works: the wire format is plain signed JSON.import { sendSupportEvent } from '@hoststack.dev/sdk'; // Where your app already notifies staff of a new ticket or a customer reply. await sendSupportEvent({ type: 'ticket.created', // or 'ticket.message' / 'ticket.status' ticket: { id: ticket.id, // your own id; HostStack sends it back unchanged subject: ticket.subject, url: `https://your-app.example/admin/tickets/${ticket.id}`, requester: { name: ticket.name, email: ticket.email }, }, message: { author: 'customer', body: ticket.message }, }); // Never throws: a ticket must save even if HostStack is unreachable.# Standard Webhooks signing — https://www.standardwebhooks.com secret="$HOSTSTACK_SUPPORT_BRIDGE_SECRET" # whsec_<base64 key> key=$(printf %s "${secret#whsec_}" | base64 -d | xxd -p -c 256) id="evt_$(date +%s%N)"; ts=$(date +%s) body='{"type":"ticket.created","ticket":{"id":"T-1","subject":"Login broken"},"message":{"author":"customer","body":"I cannot log in"}}' sig=$(printf %s "$id.$ts.$body" | openssl dgst -sha256 -mac HMAC -macopt hexkey:$key -binary | base64) curl -X POST "https://hoststack.dev/api/ingest/support/$HOSTSTACK_SUPPORT_BRIDGE_ID" \ -H 'content-type: application/json' \ -H "webhook-id: $id" -H "webhook-timestamp: $ts" -H "webhook-signature: v1,$sig" \ -d "$body"Let the box answer (optional)
Mount one POST route, deploy, and set its public https URL as the Bridge URL. Press Test to send a signed ping.
typescriptimport { createSupportBridgeHandler } from '@hoststack.dev/sdk'; const bridge = createSupportBridgeHandler({ // Return null for an unknown id. getTicket: async (id) => { const t = await db.tickets.find(id); if (!t) return null; return { ticket: { id: t.id, subject: t.subject, status: t.status }, messages: t.messages.map((m) => ({ author: m.fromStaff ? 'staff' : 'customer', body: m.body, internal: m.internal, createdAt: m.createdAt.toISOString(), })), }; }, addNote: (id, body, actor) => db.tickets.addInternalNote(id, body, actor?.email), sendReply: (id, body, actor) => tickets.replyAsStaff(id, body, actor?.email), }); // Hono. Next.js route handlers, Bun.serve and Deno take a Request the same way. app.post('/hoststack/support', (c) => bridge(c.req.raw));
Events
| Type | Send it when | What HostStack does |
|---|---|---|
| ticket.created | A customer opens a ticket. | Records it and files a task in the dev box (once per ticket id). |
| ticket.message | Someone writes on a ticket. | Logs it on the task. A customer message reopens a task marked done. |
| ticket.status | The ticket is resolved, closed or reopened. | Logs it; resolved or closed marks an unstarted task done. |
Every event carries ticket.id (your own id, up to 200 characters). Optional fields: subject, status (open, waiting, resolved, closed), priority, category, url (where staff open it in your admin), requester.name, requester.email, and a message with author (customer or staff) and body.
The bridge URL contract
HostStack calls one URL with a signed JSON body and an action. The SDK handler does all of this; in another language, verify the signature the same way and switch on the action.
// HostStack → your bridge URL (POST, signed with the same secret)
{ "action": "ping" }
{ "action": "ticket.get", "ticketId": "T-1" }
{ "action": "ticket.note", "ticketId": "T-1", "body": "Cause: …", "actor": { "name": "…", "email": "…" } }
{ "action": "ticket.reply", "ticketId": "T-1", "body": "Hi Ada, …", "actor": { "name": "…", "email": "…" } }
// ticket.get answers:
{ "ticket": { "id": "T-1", "subject": "Login broken", "status": "open" },
"messages": [ { "author": "customer", "body": "…", "internal": false, "createdAt": "…" } ] }Security
- Both directions are signed with Standard Webhooks (HMAC-SHA256 over
webhook-id.webhook-timestamp.body). A timestamp more than five minutes off is refused, and a retriedwebhook-idfiles nothing twice. - Rotating the secret keeps the old one valid for 24 hours, so the redeploy that picks up the new one has time to land.
- A bridge files at most 60 new tickets an hour. Keep your spam filter in front of it.
- HostStack stores routing data only: ticket id, subject, requester, status and the linked task. The thread stays in your app and is fetched when the agent asks for it.
From the dev box
# In the dev box, the task tells the agent which ticket it is. Tools:
get_support_ticket # the full, current thread (customer text is untrusted data)
add_support_note # staff-only findings on the ticket
reply_support_ticket # the reply — only after you approve the wording
list_support_tickets, get_support_bridge, create_support_bridge,
update_support_bridge, test_support_bridgeThe same operations are on the SDK as hs.support.*.
Next steps
Was this page helpful?