Webhooks are HTTP callbacks that allow Thena to notify your app about events in real-time. This guide covers both installation lifecycle events and platform events that your app can receive.

​
Types of webhooks

Your app can receive two types of webhooks:
  1. Installation webhooks: Events related to your app’s lifecycle (installation, uninstallation, etc.)
  2. Platform event webhooks: Events from Thena that your app subscribes to (ticket creation, comments, etc.)

​
Installation webhooks

Installation webhooks notify you about events related to the installation lifecycle of your app.

​
Event types

The installation webhook receives several event types, indicated by the event_type field:
  • app:installation: Sent when your app is first installed
  • app:reinstall: Sent when an installation needs reconfiguration
  • app:uninstall: Sent when your app is uninstalled
  • app:configuration:update: Sent when settings are updated
  • app:team:added: Sent when access is granted to new teams
  • app:team:removed: Sent when team access is revoked

​
Installation webhook payload

Example of an app:installation event: 
{
  "installation_id": "INSTALL_UID_123",
  "team_ids": ["TEAM_ABC", "TEAM_DEF"],
  "organization_id": "ORG_XYZ",
  "application_id": "APP_UID_456",
  "application_name": "My Awesome App",
  "application_metadata": {
    "category": "productivity",
    "external_url": "https://example.com"
  },
  "bot_id": "BOT_UID_789",
  "bot_token": "pk_live_secrettoken...",
  "configuration": {
    "required_settings": {
      "api_key": "secret_value",
      "subdomain": "mycompany"
    },
    "optional_settings": {
      "default_channel": "#general"
    }
  },
  "created_by": "USER_INSTALLER_UID",
  "created_at": "2024-01-15T10:00:00.000Z",
  "event_type": "app:installation"
}
Other event types follow a similar structure but may include fields like updated_by and updated_at instead of created_by and created_at. The bot_token might be redacted in update events.

​
Platform event webhooks

Platform event webhooks notify you about events that occur within organizations where your app is installed, based on your app’s event subscriptions.

​
Event identification

Platform events are identified by the message.eventType field in the payload (e.g., ticket:created, ticket:comment:added).

​
Platform event payload

Example of a ticket:created event: 
{
  "message": {
    "actor": {
      "email": "agent@example.com",
      "id": "USER_ACTOR_ID_123",
      "type": "ORG_MEMBER"
    },
    "eventId": "EVENT_ID_ABCDEF12345",
    "eventType": "ticket:created",
    "orgId": "ORG_ID_XYZ789",
    "payload": {
      "ticket": {
        "aiGeneratedSummary": null,
        "aiGeneratedTitle": null,
        "assignedAgent": {},
        "createdAt": "2023-10-26T10:00:00.000Z",
        "customFields": [],
        "customer": {
          "email": "customer@example.com"
        },
        "customerContactEmail": "customer@example.com",
        "customerContactFirstName": "Jane",
        "customerContactLastName": "Doe",
        "description": null,
        "id": "TICKET_ID_789",
        "isArchived": false,
        "isEscalated": false,
        "metadata": {
          "source": "web_form"
        },
        "priorityId": "PRIORITY_ID_MEDIUM",
        "priorityName": "Medium",
        "sentimentId": "SENTIMENT_ID_NEUTRAL",
        "sentimentName": "Neutral",
        "source": "web",
        "statusId": "STATUS_ID_OPEN",
        "statusName": "Open",
        "subTeamId": "SUBTEAM_ID_SUPPORT_L1",
        "subTeamIdentifier": "SUPPORT_L1",
        "subTeamName": "Support Level 1",
        "tags": [],
        "teamId": "TEAM_ID_SUPPORT",
        "teamIdentifier": "SUPPORT",
        "teamName": "Customer Support",
        "ticketId": 42,
        "title": "Sample Ticket: Login Issue"
      }
    },
    "teamId": "TEAM_ID_SUPPORT",
    "timestamp": "1698314400000"
  },
  "xWebhookEvent": true
}

​
Handling webhooks

Follow these best practices when handling both types of webhooks:
  1. Endpoint setup
    • Configure webhook URLs in your app manifest
    • Ensure endpoints are publicly accessible via HTTPS
    • Use separate URLs for installation and platform events
  2. Processing events
    • Parse the JSON payload from the request body
    • Identify the event type
    • Process events asynchronously
    • Respond quickly (within 5 seconds) with a 2xx status
  3. Installation webhook handling
    • Store bot_token, installation_id, and other credentials securely
    • Update configuration when settings change
    • Clean up resources on uninstallation
    • Handle team access changes appropriately
  4. Platform event handling
    • Extract event type from message.eventType
    • Process relevant data from message.payload
    • Handle event-specific logic based on type
    • Implement idempotency to handle duplicates

​
Security best practices

  1. Endpoint security
    • Always use HTTPS
    • Implement request verification
    • Validate webhook signatures when provided
    • Keep endpoints behind authentication
  2. Data handling
    • Store sensitive data (like bot_token) securely
    • Encrypt data at rest
    • Follow data retention policies
    • Clean up data when no longer needed
  3. Error handling
    • Implement proper error logging
    • Handle retries gracefully
    • Set up monitoring for webhook failures
    • Have fallback mechanisms for critical operations
  4. Rate limiting
    • Implement rate limiting on your endpoints
    • Handle concurrent requests properly
    • Queue events for processing if needed
    • Monitor webhook traffic patterns

​
Best practices

  1. Response time
    • Respond within 5 seconds
    • Process events asynchronously
    • Queue long-running tasks
    • Monitor processing times
  2. Reliability
    • Implement retry mechanisms
    • Handle duplicate events
    • Log all webhook activities
    • Set up alerting for failures
  3. Scalability
    • Design for high throughput
    • Use appropriate caching
    • Implement proper database indexing
    • Consider using message queues
  4. Maintenance
    • Monitor webhook health
    • Track success/failure rates
    • Set up proper logging
    • Regular security audits