Skip to content

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

  1. Create the bridge

    On the service’s Support tab, press Create support bridge. HostStack writes HOSTSTACK_SUPPORT_BRIDGE_ID and HOSTSTACK_SUPPORT_BRIDGE_SECRET into the service’s env vars; they apply on the next deploy. An agent in your dev box can do this with create_support_bridge.

  2. Report tickets

    Call sendSupportEvent where 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.
  3. 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.

    typescript
    import { 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

TypeSend it whenWhat HostStack does
ticket.createdA customer opens a ticket.Records it and files a task in the dev box (once per ticket id).
ticket.messageSomeone writes on a ticket.Logs it on the task. A customer message reopens a task marked done.
ticket.statusThe 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.

json
// 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 retried webhook-id files 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

text
# 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_bridge

The same operations are on the SDK as hs.support.*.

Next steps

Was this page helpful?