Overview

​

Developer quickstart

1. Create an app manifest with minimal fields (name, scopes, events).
2. Host a webhook that accepts platform events and returns 2xx quickly.
3. Use the bot token from the installation event to call Activities/APIs.
4. Store configuration securely and reference it from Activities.
5. Add one Activity and one event handler end-to-end before scaling up.

​

Minimal app (manifest + handler)

// manifest.json
{
  "app": { "name": "Sample App" },
  "scopes": { "required": ["tickets:read", "comments:write"] },
  "events": { "subscribe": [{ "event": "ticket:created" }] },
  "activities": [
    {
      "name": "notify_assignee",
      "description": "Notify the assigned agent",
      "http_config": {
        "headers": { "Content-Type": "application/json" },
        "httpVerb": "POST",
        "endpoint_url": "https://example.com/notify"
      },
      "request_schema": {
        "type": "object",
        "properties": { "ticketId": { "type": "string" } }
      }
    }
  ]
}

// webhook.js
import express from "express";
const app = express();
app.use(express.json());

app.post("/webhook/app", async (req, res) => {
  const event = req.body;
  if (!event?.eventType) return res.status(400).send("Invalid");
  res.status(200).send("OK");

  if (event.eventType === "ticket:created") {
    await notifyAssignee(event.payload.ticket);
  }
});

app.listen(3001);

​

Production checklist

• Enforce idempotency using eventId.
• Process asynchronously; keep webhook fast.
• Store bot tokens and configuration securely.
• Validate event payloads and activity responses.
• Add monitoring for failed events/activities.

​

Architecture overview

​

Core components

1. Event system
   • Central communication layer
   • Handles real-time updates
   • Manages app lifecycle events
   • Processes user interactions
2. Authentication
   • Bot token-based authentication
   • Secure installation flow
   • Automatic token management
3. Authorization
   • Permission-based access control
   • Scoped resource access
   • User-level permissions
4. Events
   • Subscribe to platform events
   • Publish custom events
   • Handle real-time updates
   • Process state changes
5. Activities
   • HTTP-based operations
   • Pre-configured API calls
   • Custom business logic
   • External service integration

​

How events work

​

Key events

1. Installation events When your app is installed in a workspace, you’ll receive an installation event with the bot token and other details:
   {
     "event_type": "app:installation",
     "application_id": "APP123456789",
     "application_name": "Sample App",
     "application_metadata": {
       "title": "Sample Integration",
       "category": "productivity",
       "capabilities": [
         "Data Management",
         "Workflow Automation"
       ],
       "pricing": {
         "monthly": 999,
         "yearly": 9990
       },
       "rating": 4.5
     },
     "bot_id": "BOT123456",
     "bot_token": "pk_live_sample.token123456",
     "organization_id": "ORG123456",
     "team_ids": ["TEAM123456"],
     "created_at": "2024-01-01T12:00:00.000Z",
     "created_by": "USER123456"
   }
   
2. Platform events Your app can subscribe to various platform events. Here’s an example of a ticket comment event:
   {
     "message": {
       "actor": {
         "id": "USER123456",
         "email": "user@example.com",
         "type": "ORG_ADMIN"
       },
       "eventType": "ticket:comment:added",
       "orgId": "ORG123456",
       "payload": {
         "comment": {
           "id": "COMMENT123456",
           "content": "This is a sample comment",
           "contentHtml": "<p>This is a sample comment</p>",
           "contentMarkdown": "This is a sample comment",
           "commentType": "comment",
           "commentVisibility": "public",
           "author": {
             "id": "USER123456",
             "name": "Sample User",
             "email": "user@example.com",
             "avatarUrl": "https://example.com/avatar.jpg"
           },
           "teamId": "TEAM123456",
           "createdAt": "2024-01-01T12:00:00.000Z",
           "updatedAt": "2024-01-01T12:00:00.000Z"
         },
         "ticket": {
           "id": "TICKET123456",
           "title": "Sample support request"
         }
       },
       "eventId": "EVENT123456",
       "timestamp": "1704110400000"
     },
     "xWebhookEvent": true
   }
   

​

Security model

1. Installation security
   • Secure bot token generation
   • Workspace-scoped access
2. Request authentication
   • Token validation on each request
   • Request signing
   • Secure payload transmission
3. Data access control
   • Resource-level permissions
   • User context validation
   • Data encryption in transit

​

Building blocks

​

Events

// Example event subscription
{
  events: {
    // Installation event handler
    'app:installation': async (event) => {
      const { bot_token, organization_id, team_ids } = event;
      // Store bot token securely
      // Initialize app for the organization
    },

    // Ticket comment event handler
    'ticket:comment:added': async (event) => {
      const {
        payload: {
          comment: { content, author },
          ticket: { id: ticketId }
        }
      } = event.message;
      // Process new comment
      // Update external systems
    }
  }
}

​

Activities

// Example activity definition
{
  "name": "create_contact",
  "description": "Creates a new contact in Hubspot",
  "http_config": {
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer ${configuration.required_settings.hubspot_api_key}"
    },
    "httpVerb": "POST",
    "endpoint_url": "https://api.hubapi.com/crm/v3/objects/contacts"
  },
  "request_schema": {
    "properties": {
      "email": {
        "type": "string",
        "description": "Contact's email address"
      },
      "company": {
        "type": "string",
        "description": "Company name"
      },
      "lastname": {
        "type": "string",
        "description": "Contact's last name"
      },
      "firstname": {
        "type": "string",
        "description": "Contact's first name"
      }
    }
  },
  "response_schema": {
    "id": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "description": "Additional information about the created contact"
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    },
    "properties": {
      "type": "object"
    }
  }
}