Webhooks

Set up webhooks to connect Hunch with your existing tools and workflows.

What are Webhooks?

Webhooks allow Hunch to send data to your server when specific events occur. This enables you to:

• Route conversations to human agents
• Integrate with CRM systems
• Send notifications to Slack/Discord
• Log conversations to your database
• Trigger custom workflows

Setting Up Webhooks

1. In your Hunch dashboard, go to your website settings
2. Find the Human Handoff Webhook section
3. Enter your webhook URL
4. Save changes

Webhook Payload

When a session needs human intervention, Hunch sends a POST request to your webhook URL:

{
  "session_id": "abc123",
  "website_id": "xyz789",
  "website_url": "https://example.com",
  "messages": [
    {
      "role": "user",
      "content": "I need help with my order"
    },
    {
      "role": "assistant", 
      "content": "I'd be happy to help with your order..."
    }
  ],
  "started_at": "2024-01-15T10:30:00Z",
  "triggered_by": "ai_confidence_low"
}

Webhook Events

Human Handoff

Triggered when:

• AI confidence is low
• Customer requests human agent
• Custom trigger words detected
• Session duration exceeds limit

Handling Webhooks

Example using Express.js:

app.post('/webhook/handoff', express.json(), (req, res) => {
  const { session_id, messages, website_url } = req.body;
  
  // Route to your support team
  await sendToSlack({
    text: `New support request from ${website_url}`,
    blocks: [
      {
        type: "section",
        text: {
          type: "mrkdwn",
          text: `*Session:* ${session_id}\n*Website:* ${website_url}`
        }
      }
    ]
  });
  
  res.status(200).send('OK');
});

Testing Webhooks

Use a tool like webhook.site to test your webhook configuration:

1. Create a test webhook URL
2. Enter it in your Hunch dashboard
3. Trigger a handoff event
4. Check the webhook.site dashboard for the request

Security

For production webhooks:

• Use HTTPS URLs
• Validate the webhook signature if provided
• Implement authentication in your endpoint
• Handle failures gracefully with retries