Skip to main content

​
List Integrations

Get all configured integrations for a workspace. 
const res = await client.integration.list.$get({ 
  workspaceSlug: "acme" 
})
const { integrations } = await res.json()
Type: Private Procedure (requires admin permission)
​
workspaceSlug
string
required
Workspace slug
​
integrations
array
Permissions:
  • User must be workspace owner or admin
  • Returns 403 if user lacks permission
  • Returns 404 if workspace not found

​
Connect Integration

Connect a webhook integration to the workspace. 
const res = await client.integration.connect.$post({
  workspaceSlug: "acme",
  type: "slack",
  webhookUrl: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
})
const { success, message } = await res.json()
Type: Private Procedure (requires admin permission)
​
workspaceSlug
string
required
Workspace slug
​
type
string
required
Integration type: “slack”, “discord”, or “webhook”
​
webhookUrl
string
required
Webhook URL endpoint
​
success
boolean
Whether connection was successful
​
message
string
Success or error message
Integration Types:
Setup:
  1. Create a Slack app at api.slack.com/apps
  2. Enable Incoming Webhooks
  3. Add webhook to workspace
  4. Copy webhook URL
  5. Use in this endpoint
Events sent:
  • New posts
  • Post status changes
  • New comments
Plan Requirements:
  • Integrations require Starter or Professional plan
  • Free plan users receive 403 error
Behavior:
  • If integration exists: Updates webhook URL and activates
  • If new integration: Creates new integration record
  • Only one integration per type per workspace
Connecting an integration overwrites the previous webhook URL for that type.

​
Disconnect Integration

Remove a webhook integration from the workspace. 
const res = await client.integration.disconnect.$post({
  workspaceSlug: "acme",
  type: "slack"
})
const { success, message } = await res.json()
Type: Private Procedure (requires admin permission)
​
workspaceSlug
string
required
Workspace slug
​
type
string
required
Integration type to disconnect
​
success
boolean
Whether disconnection was successful
​
message
string
Success or error message
Behavior:
  • Permanently deletes the integration
  • Stops all webhook notifications
  • Returns 404 if integration doesn’t exist

​
Test Integration

Send a test notification to verify webhook configuration. 
const res = await client.integration.test.$post({
  workspaceSlug: "acme",
  type: "slack"
})
const { success, message } = await res.json()
Type: Private Procedure (requires admin permission)
​
workspaceSlug
string
required
Workspace slug
​
type
string
required
Integration type to test
​
success
boolean
Whether test notification was sent successfully
​
message
string
Result message
Test Notification:
  • Sends a sample notification to the configured webhook
  • Includes workspace name in the message
  • Validates webhook URL is reachable
  • Returns error if webhook returns non-2xx status
Use Cases:
  • Verify webhook URL is correct
  • Test channel/room permissions
  • Confirm notification format
  • Troubleshoot connection issues

​
Webhook Payload Format

Webhooks receive POST requests with the following payload structure:

​
New Post Event

{
  "event": "post.created",
  "workspace": {
    "id": "ws_123",
    "name": "ACME Inc",
    "slug": "acme"
  },
  "post": {
    "id": "post_456",
    "title": "Add dark mode",
    "content": "Please add a dark mode option...",
    "url": "https://acme.featul.com/posts/add-dark-mode",
    "upvotes": 1,
    "board": "Features",
    "status": "pending",
    "author": {
      "name": "John Doe",
      "email": "[email protected]"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

​
Status Change Event

{
  "event": "post.status_changed",
  "workspace": { /* ... */ },
  "post": { /* ... */ },
  "changes": {
    "status": {
      "from": "pending",
      "to": "planned"
    }
  }
}

​
New Comment Event

{
  "event": "comment.created",
  "workspace": { /* ... */ },
  "post": { /* ... */ },
  "comment": {
    "id": "comment_789",
    "content": "Great idea! We're working on this.",
    "author": {
      "name": "Jane Smith",
      "role": "admin"
    },
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

​
Integration Events

Integrations are triggered by the following events:
  • post.created: New post submitted
  • post.status_changed: Roadmap status updated
  • post.pinned: Post pinned to top
  • post.featured: Post marked as featured
  • post.locked: Post locked from comments
  • comment.created: New comment added
  • comment.mention: User mentioned in comment
  • comment.reaction: Comment received reaction
  • post.upvoted: Post received upvote
  • post.milestone: Post reached vote milestone (10, 50, 100)
Event Filtering: Currently, all events are sent to all integrations. Future versions will support:
  • Event type filtering
  • Board-specific integrations
  • Custom event rules

​
Error Handling

Webhook Delivery:
  • Timeout: 10 seconds
  • Retries: 3 attempts with exponential backoff
  • Success: HTTP 2xx response
  • Failure: Any other status or timeout
Common Errors:
​
403
Forbidden
Integrations not available on current plan
​
404
Not Found
Workspace or integration not found
​
500
Internal Error
Failed to send webhook notification
Debugging Failed Webhooks:
  1. Use the test endpoint to verify connectivity
  2. Check webhook URL is publicly accessible
  3. Verify HTTPS (HTTP not supported)
  4. Ensure endpoint returns 2xx status
  5. Check firewall/security group rules
Use services like webhook.site or RequestBin to test webhook payloads during development.

Build docs developers (and LLMs) love

Get started for freeTalk to us