Threadhound Logo
ThreadHound
DevelopersDashboard

Webhooks

What are Webhooks?

Webhooks allow you to receive real-time HTTP notifications when specific events occur in your ThreadHound community. Instead of repeatedly polling our API for changes, webhooks push data to your application as events happen.

When a configured event occurs, ThreadHound sends an HTTP POST request to the URL you specified, containing details about the event in JSON format.

Setting Up Webhooks

  1. Navigate to your community settings
  2. Click on "Webhooks" in the Settings menu
  3. Click "Add Webhook"
  4. Select the webhook type (event) you want to receive
  5. For chat-related webhooks, select which chat groups should trigger the webhook
  6. Enter your webhook endpoint URL (must be HTTPS in production)
  7. Click "Create Webhook"
  8. Use the "Test Webhook" button to verify your endpoint is working

Available Webhook Types

Chat Message Events

Webhook Type: chatmessage-crud

Triggered when a chat message is created or updated in real-time. This excludes messages ingested via batch imports.

Action Types:

  • created - A new message has arrived
  • updated - An existing message has been modified

Example Payload:

Example Response
{
  "webhookType": "chatmessage-crud",
  "actionType": "created",
  "payload": {
    "communityId": "507f1f77bcf86cd799439011",
    "timestamp": "2026-02-18T10:30:00.000Z",
    "messageId": "507f1f77bcf86cd799439012",
    "threadId": "507f1f77bcf86cd799439013",
    "groupId": "507f1f77bcf86cd799439014",
    "groupName": "General Chat",
    "senderId": "507f1f77bcf86cd799439015",
    "senderName": "John Doe",
    "text": "Hello world!",
    "messageTimestamp": "2026-02-18T10:30:00.000Z"
  }
}

Chat Thread Events

Webhook Type: chatthread-crud

Triggered when a thread is enriched or re-enriched with AI-generated insights.

Action Types:

  • created - Thread has been enriched for the first time
  • updated - Thread has been re-enriched with new insights

Example Payload:

Example Response
{
  "webhookType": "chatthread-crud",
  "actionType": "updated",
  "payload": {
    "communityId": "507f1f77bcf86cd799439011",
    "timestamp": "2026-02-18T10:35:00.000Z",
    "threadId": "507f1f77bcf86cd799439013",
    "groupId": "507f1f77bcf86cd799439014",
    "groupName": "General Chat",
    "title": "Discussion about webhooks",
    "summary": "The team discusses implementing a webhook system...",
    "participantCount": 5,
    "messageCount": 12
  }
}

Webhook Data Format

All webhook payloads follow this structure:

{
  "webhookType": "string",    // Matches the webhook definition ID
  "actionType": "string",     // "created" or "updated"
  "payload": {                // Varies by webhook type
    "communityId": "string",
    "timestamp": "string",    // ISO 8601 format
    ...                       // Additional fields specific to webhook type
  }
}

Implementing a Webhook Endpoint

Your webhook endpoint should:

  • Accept HTTP POST requests
  • Process the JSON payload
  • Return a 2xx status code (200-299) to acknowledge receipt
  • Respond within 10 seconds

Example Express.js endpoint:

curl -X POST https://your-domain.com/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "webhookType": "chatmessage-crud",
    "actionType": "created",
    "payload": {
      "communityId": "507f1f77bcf86cd799439011",
      "timestamp": "2026-02-18T10:30:00.000Z"
    }
  }'

Best Practices

Process Asynchronously

Acknowledge receipt immediately (return 200) and process the webhook data asynchronously. Don't make the webhook request wait for long-running operations.

Handle Failures Gracefully

If your webhook endpoint returns a non-2xx status code, ThreadHound will automatically disable the webhook to prevent further failures. Re-enable it after fixing the issue.

Use HTTPS

Always use HTTPS endpoints in production to ensure webhook data is transmitted securely.

Test Your Endpoint

Use the "Test Webhook" button in the settings to verify your endpoint is working correctly before enabling it.

Troubleshooting

Webhook was automatically disabled

This happens when your endpoint returns a non-2xx status code or times out. Check the "Last Error" field in the webhook settings for details. Fix the issue and re-enable the webhook.

Not receiving webhook calls

  • Verify the webhook is enabled
  • Check that your URL is correct and accessible from the internet
  • Ensure the webhook is configured for the correct chat groups
  • Check your firewall/security rules allow incoming connections

Webhook timing out

Webhooks have a 10-second timeout. Make sure your endpoint responds quickly (ideally within 1-2 seconds). Process data asynchronously after acknowledging receipt.