> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Create a private webhook app to receive all platform events from Thena.

<img src="https://mintcdn.com/thena-840ce5ec/ARAy4s5pa-7wASqR/images/docs/Webhooks.webp?fit=max&auto=format&n=ARAy4s5pa-7wASqR&q=85&s=589d21b9e4398947deb1927882074134" alt="Webhooks integration in Thena" className="rounded-lg" width="2560" height="1600" data-path="images/docs/Webhooks.webp" />

Create a dedicated private webhook app which sends all the platform events from Thena to the webhook URL you add while creating the app. This is a secure way to ensure your data is sent to the receiving app.

## What are webhooks?

Webhooks are HTTP callbacks that automatically send data from one application to another when specific events occur. Think of them as "reverse APIs" - instead of your application requesting data from a service, the service automatically sends data to your application when something happens.

A webhook app in Thena allows you to receive all platform events in real-time and send them to multiple destinations. This approach gives you complete control over how you receive and process Thena platform events while maintaining the flexibility to send them to multiple destinations.

## What events are supported?

Thena publishes a comprehensive set of platform events that you can receive through webhooks. These events cover all major platform activities and are organized into logical categories:

<AccordionGroup>
  <Accordion title="Ticket events" icon="ticket">
    * **ticket:created** - New ticket creation
    * **ticket:updated** - Ticket modifications
    * **ticket:deleted** - Ticket deletion
    * **ticket:archived** - Ticket archiving
    * **ticket:assigned** - Agent assignment
    * **ticket:status:changed** - Status updates
    * **ticket:priority:changed** - Priority changes
  </Accordion>

  <Accordion title="Account events" icon="building">
    * **account:created** - New account creation
    * **account:updated** - Account modifications
    * **account:deleted** - Account deletion
    * **account-health:changed** - Health status changes
    * **account-status:changed** - Account status updates
    * **account-custom\_field\_value:added** - Custom field additions
    * **account-custom\_field\_value:removed** - Custom field removals
  </Accordion>

  <Accordion title="Comment events" icon="comments">
    * **ticket:comment:created** - New ticket comments
    * **ticket:comment:updated** - Comment modifications
    * **ticket:comment:deleted** - Comment deletion
    * **account-task:comment:created** - Task comment creation
    * **account-activity:comment:created** - Activity comment creation
    * **account-note:comment:created** - Note comment creation
  </Accordion>

  <Accordion title="User events" icon="user">
    * **user:mentioned** - User mentions in comments
    * **user:created** - New user creation
    * **user:updated** - User profile updates
    * **user:deleted** - User deletion
  </Accordion>

  <Accordion title="Organization events" icon="users">
    * **organization:created** - New organization setup
    * **organization:updated** - Organization changes
    * **organization:deleted** - Organization deletion
    * **organization:member-joined** - New member additions
    * **organization:member-left** - Member departures
    * **organization:plan-changed** - Subscription plan updates
  </Accordion>

  <Accordion title="Custom object events" icon="database">
    * **custom-object:{type}:created** - Custom object creation
    * **custom-object:{type}:updated** - Custom object updates
    * **custom-object:{type}:deleted** - Custom object deletion
    * **custom-object:{type}:field-changed** - Field value changes

    <Note>
      **Note**: Custom object events use dynamic event types based on your custom object definitions. Replace {type} with your actual custom object names (e.g., "deal", "opportunity", "lead").
    </Note>
  </Accordion>
</AccordionGroup>

## Key features

<CardGroup cols={2}>
  <Card title="Real-time event streaming" icon="timer">
    Receive all platform events from Thena in real-time through webhook endpoints.
  </Card>

  <Card title="Multiple destinations" icon="share-nodes">
    Create multiple webhook apps to send events to different services and systems.
  </Card>

  <Card title="Custom filtering" icon="filter">
    Filter and process events on your end to create custom workflows and automation.
  </Card>

  <Card title="Full control" icon="gear">
    Maintain complete control over event processing logic and data handling.
  </Card>
</CardGroup>

## How to set up webhooks in Thena

<Warning>
  **Setup requirements**: The webhook app creation requires setup through the Thena API. There is no user interface available for configuration at this time. All setup must be completed using API calls.
</Warning>

You need to make **2 API calls** for this setup:

1. **Create app** - use the curl command with the manifest to create the app
2. **Install app** - install the app in the teams whose events you want to receive

### Step 1: Create app

<Steps>
  <Step title="Prepare the curl request">
    Create a POST request to create your webhook app with the following curl command:

    ```bash theme={null}
    curl --location 'https://apps-studio.thena.ai/apps/create-app' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_API_KEY' \
    --data-raw '{
        "app_visibility": "private",
        "manifest": {
            "app": {
                "name": "Webhooks",
                "description": "Send webhoooks to third party services",
                "category": "webhooks",
                "icons": {
                    "small": "https://cdn1.iconfinder.com/data/icons/carbon-design-system-vol-8/32/webhook-1024.png",
                    "large": "https://cdn1.iconfinder.com/data/icons/carbon-design-system-vol-8/32/webhook-1024.png"
                },
                "supported_locales": [
                    "en-US"
                ],
                "slug":"webhooks"
            },
            "developer": {
                "name": "Your org name",
                "website": "https://yourorg.app",
                "support_email": "support@yourorg.app",
                "privacy_policy_url": "https://yourorg.app/privacy",
                "terms_url": "https://yourorg.app/terms",
                "documentation_url": "https://developers.yourorg.app/docs"
            },
            "integration": {
                "entry_points": {
                    "main": "https://yourorg.app/app",
                    "configuration": "https://yourorg.app/config"
                },
                "webhooks": {
                    "events": "https://your-webhook-url",
                    "installations": "https://your-webhook-url"
                },
                "interactivity": {
                    "request_url": "https://your-webhook-url",
                    "message_menu_option_url": "https://your-webhook-url"
                }
            },
            "configuration": {
                "required_settings": [],
                "optional_settings": []
            },
            "scopes": {
                "required": {
                    "platform": [
                        {
                            "scope": "webhooks:read",
                            "reason": "Read webhook data",
                            "description": "Access to read webhook information"
                        }
                    ]
                },
                "optional": {
                    "platform": []
                }
            },
            "events": {
                "subscribe": [],
                "publish": []
            },
            "activities": [],
            "metadata": {
                "is_privileged_app": false
            }
        }
    }'
    ```

    **Customize the manifest** with your organization's information:

    * Add your Thena API key in the `x-api-key` header
    * Update the `developer` section with your company details
    * Replace `webhook URLs` with your actual endpoints inside webhooks and interactivity
    * Modify the app name and description as needed

    <Note>
      Replace `YOUR_API_KEY` with your actual Thena API key. You can find this in your Thena dashboard under Organization → Personal → Security Access or visit [https://dashboard.thena.ai/organization/settings/personal/security-access](https://dashboard.thena.ai/organization/settings/personal/security-access).
    </Note>

    <Tip>
      **App visibility**: Ensure this is set to `private` since it is for internal use.
    </Tip>
  </Step>

  <Step title="Make the API call">
    Use the [Create a new app API](/api-reference/apps-platform/app-creation/create-a-new-app) to execute the curl command above.

    <Note>
      The API endpoint will validate your manifest and create the webhook app with the specified configuration.
    </Note>
  </Step>

  <Step title="Save the app ID">
    Once the app is created successfully, you will receive an API response containing:

    * `appId`: This unique identifier for your webhook app (e.g., `EGHG8R3K9HGU98JJ81W5EKQRM2X9`)
    * `clientId` and `clientSecret`: Authentication credentials for the app

    Save the `appId` as you'll need it for the next step.
  </Step>
</Steps>

### Step 2: Install app

After creating the app, you need to install it to specify which teams' events you want to receive.

<Steps>
  <Step title="Prepare the installation request">
    Create a POST request to install the webhook app with the following curl command:

    ```bash theme={null}
    curl --location 'https://apps-studio.thena.ai/apps/install' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: YOUR_API_KEY' \
    --data '{
      "teamIds": [
        "TAHGVCBHGT",
        "THHGHBNIYF"
      ],
      "appId": "YOUR_APP_ID",
      "appConfiguration": {
        "required_settings": [],
        "optional_settings": []
      }
    }'
    ```

    **Customize the installation request** with your specific values:

    * Add your Thena API key in the `x-api-key` header
    * Replace `YOUR_APP_ID` with the `appId` you received from Step 1 (e.g., `EGHG8R3K9HGU98JJ81W5EKQRM2X9`)
    * Update the `teamIds` array with your actual team IDs

    <Note>
      **Finding team IDs**: You can find your team ID from the URL when you're in the team dashboard in Thena. For example, if the URL is `https://dashboard.thena.ai/dashboard/T123NHFDRF`, then the team ID is `T123NHFDRF`.
    </Note>

    <Tip>
      **Multiple teams**: You can install the webhook app to multiple teams at once by including all relevant team IDs in the `teamIds` array.
    </Tip>
  </Step>

  <Step title="Make the API call">
    Use the [Install an app API](/api-reference/apps-platform/app-installation/install-an-app) to execute the curl command above.

    <Note>
      The API endpoint will handle connecting your webhook app to the specified Thena teams.
    </Note>
  </Step>

  <Step title="Verify the installation">
    After successful installation, you should see the webhook app appear in your app settings. The app will now start sending events from the specified teams to the webhook URL.
  </Step>
</Steps>

## What can you do with multiple webhook apps?

You can create **as many webhook private apps as needed** using this approach to send events to multiple destinations:

<CardGroup cols={2}>
  <Card title="Zapier, n8n, Make integration" icon="network-wired">
    Send events to Zapier, n8n, Make for workflow automation and integration with multiple apps.
  </Card>

  <Card title="Internal monitoring" icon="chart-line">
    Route events to your internal monitoring and alerting systems.
  </Card>

  <Card title="Data warehouse" icon="database">
    Stream events to data warehouses for analytics and reporting.
  </Card>

  <Card title="Slack notifications" icon="slack">
    Send filtered events to Slack channels for team notifications.
  </Card>
</CardGroup>

<Info>
  **App isolation**: Each webhook app operates independently, so you can have different configurations, webhook URLs, and team assignments for different use cases.
</Info>

## How do you process webhook events?

Based on the platform events you receive, you can add **filtering on your end** and create any workflows:

<Info>
  **Event filtering**: You can filter these events on your webhook endpoint to process only the events relevant to your use case. Each event includes rich metadata and payload data for comprehensive integration.
</Info>

### Filtering examples

```javascript theme={null}
// Example webhook handler
app.post('/webhook', (req, res) => {
    const event = req.body;
    
    // Filter for specific event types
    if (event.type === 'ticket:created') {
        // Handle new contact creation
        processNewContact(event.data);
    }
    
    // Filter for specific teams
    if (event.team_id === 'team_123') {
        // Process team-specific events
        handleTeamEvent(event);
    }
    
    // Filter for specific users
    if (event.user_id === 'user_456') {
        // Process user-specific events
        handleUserEvent(event);
    }
    
    res.status(200).send('OK');
});
```

### No-code filtering

If you're using no-code automation tools like Zapier, n8n, or Make, you can filter events using the **Message Event Type** field instead of writing code. For example:

* Filter by `ticket:created` to process only new ticket events
* Filter by `ticket:comment:reaction:added` to handle reaction events
* Filter by `account:updated` to respond to account changes
* Use pattern matching like `ticket:*` to catch all ticket-related events

This approach allows you to create sophisticated workflows without writing custom filtering logic.

### Workflow examples

<CardGroup cols={2}>
  <Card title="Automated notifications" icon="bell">
    Send Slack messages when high-priority tickets are created or escalated.
  </Card>

  <Card title="Data sync" icon="rotate">
    Update external CRM systems when contacts are modified or created.
  </Card>

  <Card title="Analytics tracking" icon="chart-pie">
    Track user engagement patterns and generate real-time reports.
  </Card>

  <Card title="Compliance logging" icon="chart-line">
    Log all data changes for audit purposes and regulatory compliance.
  </Card>
</CardGroup>

<Info>
  **Getting help**: If you encounter issues during setup, check the validation requirements above and ensure all required fields are properly configured in your manifest.
</Info>