Webhook based

Webhook-Based Integrations

New to building integrations? Start with our step-by-step contributor guide for a quick overview.

Webhook-based integrations receive HTTP callbacks from external services for real-time synchronization. This reference guide uses Slack as the detailed example.

When to Use Webhooks

Choose webhook-based integrations when:

The service provides real-time webhook events
You need instant synchronization (chat messages, notifications)
Events are user-triggered and need immediate capture
The service has robust webhook infrastructure

Architecture Overview

External Service (Slack)
        ↓
    Webhook Event
        ↓
    Core Webhook Endpoint
        ↓
    Integration IDENTIFY → Extract user ID
        ↓
    Integration PROCESS → Create activity
        ↓
    Knowledge Graph

Event Flow

1. SETUP Event

When a user connects their account via OAuth:

// account-create.ts
export async function integrationCreate(data: any) {
  const { oauthResponse } = data;

  // Get user info from service
  const user = await getSlackUserInfo(oauthResponse.access_token);

  return [{
    type: 'account',
    data: {
      accountId: user.user_id,
      config: {
        access_token: oauthResponse.access_token,
        refresh_token: oauthResponse.refresh_token,
        // Pass token to MCP tools
        mcp: { tokens: { access_token: oauthResponse.access_token } }
      },
      settings: {
        username: user.user,
        team_id: user.team_id
      }
    }
  }];
}

2. IDENTIFY Event

When a webhook event arrives, extract the user identifier for routing:

// index.ts
case IntegrationEventType.IDENTIFY:
  // Extract user ID from Slack event
  return [{
    type: 'identifier',
    data: eventPayload.eventBody.event.event.user ||
          eventPayload.eventBody.event.event.message.user
  }];

This tells Core which user’s knowledge graph to update with the activity.

3. PROCESS Event

Process the webhook event and create activity messages:

// create-activity.ts
export const createActivityEvent = async (eventData: any, config: any) => {
  const event = eventData.event;
  const accessToken = config.access_token;

  // Handle different event types
  if (event.type === 'reaction_added' && event.reaction === 'eyes') {
    // User reacted with 👀 emoji - capture for knowledge graph

    // 1. Get the original message
    const message = await getMessage(accessToken, event.item.channel, event.item.ts);

    // 2. Get user details and channel info
    const [userDetails, channelInfo] = await Promise.all([
      getUserDetails([message.user], accessToken),
      getConversationInfo(accessToken, event.item.channel)
    ]);

    // 3. Build contextual description
    const text = `User ${userDetails[0].real_name} reacted with eyes emoji ` +
                 `in channel ${channelInfo.name}. Content: '${message.text}'`;

    // 4. Get permalink for deep linking
    const permalink = await getPermalink(accessToken, event.item.channel, event.item.ts);

    // 5. Return activity message
    return [{
      type: 'activity',
      data: {
        text,
        sourceURL: permalink.data.permalink
      }
    }];
  }

  if (event.type === 'message') {
    // Handle message events
    const text = `Message in channel: '${event.text}'`;
    const permalink = await getPermalink(accessToken, event.channel, event.ts);

    return [{
      type: 'activity',
      data: {
        text,
        sourceURL: permalink.data.permalink
      }
    }];
  }

  // Return empty array for unhandled events
  return [];
};

Full Example: Slack Integration

spec.json

{
  "name": "Slack extension",
  "key": "slack",
  "description": "Connect your workspace to Slack",
  "icon": "slack",

  "auth": {
    "OAuth2": {
      "token_url": "https://slack.com/api/oauth.v2.access",
      "authorization_url": "https://slack.com/oauth/v2/authorize",
      "scopes": [
        "channels:read",
        "channels:history",
        "chat:write",
        "reactions:read",
        "reactions:write",
        "users:read",
        "users.profile:read"
      ],
      "scope_identifier": "user_scope",
      "scope_separator": ","
    }
  },

  "mcp": {
    "type": "stdio",
    "url": "https://integrations.heysol.ai/slack/mcp/slack-mcp-server",
    "args": [],
    "env": {
      "SLACK_MCP_XOXP_TOKEN": "${config:access_token}",
      "SLACK_MCP_ADD_MESSAGE_TOOL": true
    }
  }
}

index.ts

import { integrationCreate } from './account-create';
import { createActivityEvent } from './create-activity';
import {
  IntegrationCLI,
  IntegrationEventPayload,
  IntegrationEventType,
  Spec,
} from '@redplanethq/sdk';

export async function run(eventPayload: IntegrationEventPayload) {
  switch (eventPayload.event) {
    case IntegrationEventType.SETUP:
      return await integrationCreate(eventPayload.eventBody);

    case IntegrationEventType.IDENTIFY:
      // Extract user ID from Slack event
      return [{
        type: 'identifier',
        data: eventPayload.eventBody.event.event.user ||
              eventPayload.eventBody.event.event.message.user,
      }];

    case IntegrationEventType.PROCESS:
      // Process webhook event
      return createActivityEvent(
        eventPayload.eventBody.eventData,
        eventPayload.config
      );

    default:
      return [{ type: 'error', data: `Unknown event type: ${eventPayload.event}` }];
  }
}

class SlackCLI extends IntegrationCLI {
  constructor() {
    super('slack', '1.0.0');
  }

  protected async handleEvent(eventPayload: IntegrationEventPayload): Promise<any> {
    return await run(eventPayload);
  }

  protected async getSpec(): Promise<Spec> {
    // Return spec configuration
    return {
      name: 'Slack extension',
      key: 'slack',
      // ... rest of spec
    };
  }
}

function main() {
  const slackCLI = new SlackCLI();
  slackCLI.parse();
}

main();

create-activity.ts

import axios from 'axios';

interface SlackActivityCreateParams {
  text: string;
  sourceURL: string;
}

function createActivityMessage(params: SlackActivityCreateParams) {
  return {
    type: 'activity',
    data: {
      text: params.text,
      sourceURL: params.sourceURL,
    },
  };
}

async function getMessage(accessToken: string, channel: string, ts: string) {
  const result = await axios.get('https://slack.com/api/conversations.history', {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    params: {
      channel,
      latest: ts,
      inclusive: true,
      limit: 1,
    },
  });

  return result.data.messages?.[0];
}

async function getConversationInfo(accessToken: string, channel: string) {
  const result = await axios.get('https://slack.com/api/conversations.info', {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
    params: { channel },
  });

  return result.data.channel;
}

async function getPermalink(accessToken: string, channel: string, ts: string) {
  return await axios.get(
    `https://slack.com/api/chat.getPermalink?channel=${channel}&message_ts=${ts}`,
    {
      headers: { Authorization: `Bearer ${accessToken}` },
    }
  );
}

export const createActivityEvent = async (eventData: any, config: any) {
  const event = eventData.event;

  if (!config) {
    throw new Error('Integration configuration not found');
  }

  const accessToken = config.access_token;

  // Handle reaction_added events
  if (event.type === 'reaction_added' && event.reaction === 'eyes') {
    const channel = event.item.channel;
    const ts = event.item.ts;

    // Fetch message and context
    const [eventMessage, conversationInfo] = await Promise.all([
      getMessage(accessToken, channel, ts),
      getConversationInfo(accessToken, channel)
    ]);

    // Build activity text
    const text = `User reacted with eyes emoji in channel ${conversationInfo.name}. ` +
                 `Content: '${eventMessage.text}'`;

    // Get permalink
    const permalinkResponse = await getPermalink(accessToken, channel, ts);

    return [createActivityMessage({
      text,
      sourceURL: permalinkResponse.data.permalink
    })];
  }

  // Handle message events
  if (event.type === 'message') {
    const text = `Message in channel: '${event.text}'`;
    const permalinkResponse = await getPermalink(accessToken, event.channel, event.ts);

    return [createActivityMessage({
      text,
      sourceURL: permalinkResponse.data.permalink
    })];
  }

  // Return empty array for unhandled events
  return [];
};

Best Practices

1. Event Filtering

Only process events that are relevant to the user’s knowledge graph:

// Good: Filter for specific reactions that indicate importance
if (event.type === 'reaction_added' && event.reaction === 'eyes') {
  // This is important, capture it
}

// Good: Filter for direct messages
if (conversationInfo.is_im) {
  // Direct message is usually important
}

// Bad: Capture every message (too noisy)
if (event.type === 'message') {
  // This creates too much noise
}

2. Context Enrichment

Provide rich context by fetching related data:

// Fetch related data in parallel for efficiency
const [userDetails, channelInfo, message] = await Promise.all([
  getUserDetails([userId], accessToken),
  getConversationInfo(accessToken, channelId),
  getMessage(accessToken, channelId, timestamp)
]);

// Build descriptive activity
const text = `${userDetails[0].real_name} mentioned you in ` +
             `${channelInfo.is_private ? 'private' : 'public'} channel ` +
             `${channelInfo.name}: "${message.text}"`;

3. Deep Linking

Always provide sourceURL for navigation back to the original content:

const permalinkResponse = await axios.get(
  `https://slack.com/api/chat.getPermalink?channel=${channel}&message_ts=${ts}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);

return [{
  type: 'activity',
  data: {
    text,
    sourceURL: permalinkResponse.data.permalink // Essential!
  }
}];

4. Error Handling

Handle errors gracefully without breaking the integration:

export const createActivityEvent = async (eventData: any, config: any) => {
  try {
    // Process event
    const activities = await processEvent(eventData, config);
    return activities;
  } catch (error) {
    console.error('Error processing webhook:', error);
    // Return empty array instead of throwing
    return [];
  }
};

5. User Identification

Properly extract user IDs for different event types:

case IntegrationEventType.IDENTIFY:
  // Handle different event structures
  const userId = eventPayload.eventBody.event.event.user ||      // reactions, messages
                 eventPayload.eventBody.event.event.message.user || // threaded messages
                 eventPayload.eventBody.event.event.item.user;      // other events

  return [{ type: 'identifier', data: userId }];

Testing Webhooks Locally

To test webhooks during development:

Use ngrok for local tunneling:
ngrok http 3000

Configure webhook URL in service (Slack):

https://your-ngrok-url.ngrok.io/webhooks/slack

Test events by triggering actions in Slack
Check logs for event payloads and processing

Common Event Types

Slack

message - New message posted
reaction_added - Emoji reaction added
reaction_removed - Emoji reaction removed
member_joined_channel - User joined channel
app_mention - Bot was mentioned

Get Started

Configuration

Channels

Remote Sessions

Build Integrations

Migration

Local Development

Webhook-Based Integrations

When to Use Webhooks

Architecture Overview

Event Flow

1. SETUP Event

2. IDENTIFY Event

3. PROCESS Event

Full Example: Slack Integration

spec.json

index.ts

create-activity.ts

Best Practices

1. Event Filtering

2. Context Enrichment

3. Deep Linking

4. Error Handling

5. User Identification

Testing Webhooks Locally

Common Event Types

Slack

Discord

Linear

Next Steps

​Webhook-Based Integrations

​When to Use Webhooks

​Architecture Overview

​Event Flow

​1. SETUP Event

​2. IDENTIFY Event

​3. PROCESS Event

​Full Example: Slack Integration

​spec.json

​index.ts

​create-activity.ts

​Best Practices

​1. Event Filtering

​2. Context Enrichment

​3. Deep Linking

​4. Error Handling

​5. User Identification

​Testing Webhooks Locally

​Common Event Types

​Slack

​Discord

​Linear

​Next Steps

Webhook-Based Integrations

When to Use Webhooks

Architecture Overview

Event Flow

1. SETUP Event

2. IDENTIFY Event

3. PROCESS Event

Full Example: Slack Integration

spec.json

index.ts

create-activity.ts

Best Practices

1. Event Filtering

2. Context Enrichment

3. Deep Linking

4. Error Handling

5. User Identification

Testing Webhooks Locally

Common Event Types

Slack

Discord

Linear

Next Steps