Callbacks

Callback URLs allow you to receive HTTP notifications when events occur in your Justack sessions. Set a callback_url when creating a session to receive notifications at that URL.

Setting Up Callbacks

Specify a callback_url when creating a session:

const session = await client.sessions.create({
  name: "Deployment Approval",
  recipients: ["approver@example.com"],
  notify: true,
  callbackUrl: "https://your-server.com/webhooks/justack",
});

The API will send HTTP POST requests to your callback URL when events occur in that session (e.g., when a recipient responds to an ask message).

Callback Handler Example

app.post("/webhooks/justack", async (req, res) => {
  const event = req.body;

  // Handle the event based on type
  console.log(`Received callback for session: ${event.session_id}`);

  // Process the event
  await handleSessionEvent(event);

  // Respond quickly
  res.status(200).send("OK");
});

When to Use Callbacks vs SDK

Approach	Use When
SDK (session.ask())	Your agent is running and can wait for a response in real-time
Callback URL	Your agent is serverless, batch-oriented, or can’t maintain a long-running WebSocket

With the SDK, session.ask() blocks until a response is received via WebSocket. Callback URLs provide an alternative for architectures where maintaining a persistent connection isn’t practical.

Best Practices

Respond Quickly

Return a 200 response immediately, then process the event asynchronously:

app.post("/webhooks/justack", async (req, res) => {
  // Queue for async processing
  await queue.add("process-callback", req.body);

  // Respond immediately
  res.status(200).send("OK");
});

Test Locally

Use a tunneling service like ngrok to test callbacks locally:

ngrok http 3000

Then use the ngrok URL as your callbackUrl when creating sessions.

Next Steps

• Sessions Guide - Session management
• Recipients Guide - Recipient management
• API Reference - Complete API documentation