diff --git a/.gitignore b/.gitignore index c20a5ce..d8088d0 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,8 @@ psd thumb sketch +CLAUDE.md + ### intellij ### .idea diff --git a/docs/00-index.md b/docs/00-index.md index a1e5ab3..9c4789d 100644 --- a/docs/00-index.md +++ b/docs/00-index.md @@ -1,23 +1,27 @@ --- slug: / --- -# Extend Wire with secure Apps +# Wire Apps #### Apps bring your ideas to the [Wire secure communications platform](https://wire.com/) Automate workflows, connect with third-party services, and boost collaboration. Customize Wire to fit your team's needs. All with Wire's end-to-end MLS encryption and security intact. -## How it works - Apps are separate pieces of software that communicate with Wire through a common protocol. They remain independent, but can seamlessly interact with the system and its users. -An App is a way to extend and automate your team’s experience on Wire. Send and receive messages — including assets, emojis, and interactive buttons — create and manage conversations, and integrate external services. -Apps are owned and managed at the team level. The administrator decides which Apps are installed. +To build an App, you don't have to write it from scratch, you can use the **Wire Apps SDK**. + +## What can you do with them? +1. **Extend Wire functionality**, by writing your own automations, for example an App that sends scheduled reminders or can summarize a message +2. **Connect an external system to wire**. Build an App to accept events from an API and then send a message inside Wire, like alerts or updates. Or the other way around, have actions performed inside Wire be propagated to an external software -> [Webhook](001-webhook.mdx) -## What's needed +## Get started +The Wire SDK is a developer toolkit that allows developers to build Apps(Integrations) for their team, working inside Wire's encrypted environment. Unlike most collaboration platforms where Apps run on server infrastructure outside the encrypted client boundary, Wire applications participate directly in encrypted conversations. + +What does it mean? - In Wire, an App behaves like a real participant in the conversation and receives the encryption keys needed to read and send messages. ### Develop your App using SDK @@ -38,6 +42,8 @@ Follow the [steps to onboard your App](./02-manage-apps/01-create-app.md). You own and host your app, with full control over your infrastructure and data. +Apps are owned and managed at the team level. The administrator decides which Apps are installed. + Wire never has access to the messages your App receives or sends. You need to secure your deployment and protect the data your App handles. diff --git a/docs/001-webhook.mdx b/docs/001-webhook.mdx new file mode 100644 index 0000000..b6b7e60 --- /dev/null +++ b/docs/001-webhook.mdx @@ -0,0 +1,107 @@ +# Connecting external systems + +Many business tools, monitoring platforms, ticketing systems, CI/CD pipelines or CRMs, can send an HTTP webhook whenever something happens. With the Wire SDK, you can receive those webhooks and turn them into Wire messages or conversations, keeping your team informed without leaving Wire. + +Common examples include: + +- **Jira or ServiceNow** webhook that posts a notification when a ticket opens or changes priority. +- **CI/CD pipeline** (GitHub Actions, Jenkins, GitLab) that alerts a team channel on a build failure or deployment. +- **monitoring tool** (PagerDuty, Grafana, Datadog) that fires an alert when a service degrades. +- **Zendesk or Salesforce** event that routes a new support request to the right Wire conversation. + +## Encryption by default + +On most collaboration platforms like Slack and Microsoft Teams, bots and integrations run on server infrastructure _outside_ the encrypted client boundary. The platform server can see message content before it reaches users. + +In Wire it works differently. Your SDK app joins the conversation as a real encrypted participant. It holds encryption keys, encrypts and decrypts messages, and delivers notifications end-to-end encrypted from your app to every member of the conversation. The Wire server only routes encrypted data, it never sees the content. + +This means you can pipe sensitive operational data (incident details, financial alerts, compliance notifications) into Wire conversations without it ever passing through an unencrypted layer. + +## How it works + +Your app sits between the external system and Wire. It runs two things at once: + +1. An **HTTP server** that receives the incoming webhook from the external system. +2. The **Wire SDK** that sends messages or creates conversations in response. + +```mermaid +sequenceDiagram + participant Ext as External System
(Jira, CI/CD, monitoring…) + participant App as Your App
(HTTP server + Wire SDK) + participant Wire as Wire Backend + + Ext->>App: POST /webhook (HTTP) + Note over App: Parse and format payload + App->>Wire: Send encrypted message (via SDK) + Wire-->>App: Confirmation +``` + +Your app decides what to send. The raw webhook payload stays with you while Wire only receives the message you compose from it. + +## Common patterns + +### Notification pipeline + +When an external event fires, post a formatted message to a known conversation. To make it more flexible, set the conversationId as part of the webhook URL or data to also have routing. + +```mermaid +flowchart LR + A[External event] --> B[Receive webhook] + B --> C[Format message] + C --> D[Send to Wire conversation] +``` + +This covers most alerting and reporting scenarios: deployment notifications, monitoring alerts, daily summaries, ticket updates. + + +A good example of this is the **[GitHub App](https://github.com/wireapp/github-app)**: +1. the App exposes 1 endpoint and your GitHub org is configured with a web-hook to send events on every pull request being closed +2. The App receives the event via Rest and then uses the SDK to send an encrypted message in a Wire conversation. + +### Conversation per event + +For events that need focused attention like a new incident, a critical ticket, a compliance request, your app can create a fresh conversation and add the relevant people to it. Each event gets its own thread, keeping discussions organised and searchable. + +```mermaid +flowchart LR + A[External event] --> B[Receive webhook] + B --> C[Create conversation with relevant members] + C --> D[Post initial messagewith event details] +``` + +See [creating conversations](./03-developer-interface/02-interactions/03-create-conversation.md) for how to create group and one-to-one conversations with the SDK. + +### Approval workflow + +For workflows that require a decision like approvals, acknowledgements, escalations, send a composite message with buttons. When a team member selects an option, the SDK receives the button click event and your app can trigger the next step in the workflow, all within the encrypted Wire environment. + +```mermaid +sequenceDiagram + participant Ext as External System + participant App as Your App + participant Wire as Wire + participant User as Team member + + Ext->>App: POST /webhook (approval request) + App->>Wire: Send composite message with buttons + Wire->>User: Deliver encrypted message + User->>Wire: Select button (Approve / Reject) + Wire->>App: Button click event (via SDK) + App->>Ext: Trigger next workflow step +``` + +Learn how to [compose a message with buttons](./03-developer-interface/02-interactions/01-send-message.mdx#composite-message), and react [on buttons being clicked](./03-developer-interface/01-events/06-on-button-clicked.mdx). + +## Securing your webhook endpoint + +Before acting on a webhook, always verify it came from your external system. Most platforms sign their payloads with HMAC-SHA256 and include the signature in a request header. Reject any request where the signature doesn't match. + +Store the webhook signing secret alongside your Wire API token, using a secrets manager or environment variable. See [managing app tokens](./05-secure-integration-guidelines/02-managing-app-tokens.md) for recommended storage approaches. + +## Deployment considerations + +Your app needs a stable, publicly accessible endpoint so the external system can reach it. If you're running behind a firewall or in a private network, you'll need to expose the webhook port or use a reverse proxy. + +Review the [deployment tips](./04-deployment-tips/index.md) for guidance on hosting your app and making sure it stays reachable. diff --git a/docusaurus.config.js b/docusaurus.config.js index 7ee1b2d..f10ed9d 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -70,7 +70,7 @@ const config = { position: 'right', }, { to: "/showcase", label: "Showcase", position: "left" }, - { to: "/support", label: "Support", position: "left" }, + { to: "/contact", label: "Contact", position: "left" }, { to: "/feature-requests", label: "Feature requests", position: "left" }, ], }, diff --git a/src/data/apps.tsx b/src/data/apps.tsx index ed3edaa..24cfdbf 100644 --- a/src/data/apps.tsx +++ b/src/data/apps.tsx @@ -7,8 +7,8 @@ /* eslint-disable global-require */ -import {translate} from '@docusaurus/Translate'; -import {sortBy} from '@site/src/utils/jsUtils'; +import { translate } from '@docusaurus/Translate'; +import { sortBy } from '@site/src/utils/jsUtils'; import PollIcon from './app-icons/poll.svg'; import GithubIcon from './app-icons/github.svg'; @@ -22,6 +22,7 @@ export type TagType = // For open source Apps, a link to the source code is required. | 'product' | 'kotlin' + | 'webhook' // Add apps to this list // prettier-ignore @@ -39,7 +40,7 @@ const Apps: App[] = [ description: 'Get GitHub notifications directly in Wire', icon: , source: 'https://github.com/wireapp/github-app', - tags: ['product', 'kotlin'], + tags: ['product', 'kotlin', 'webhook'], }, { title: 'Poll App', @@ -76,9 +77,9 @@ export type Tag = { color: string; }; -export const Tags: {[type in TagType]: Tag} = { +export const Tags: { [type in TagType]: Tag } = { "wire-approved": { - label: translate({message: 'Wire-approved'}), + label: translate({ message: 'Wire-approved' }), description: translate({ message: 'Explore Apps approved by Wire', @@ -88,7 +89,7 @@ export const Tags: {[type in TagType]: Tag} = { }, product: { - label: translate({message: 'Product'}), + label: translate({ message: 'Product' }), description: translate({ message: 'Apps associated to a commercial product', id: 'showcase.tag.product.description', @@ -97,13 +98,22 @@ export const Tags: {[type in TagType]: Tag} = { }, kotlin: { - label: translate({message: 'Kotlin'}), + label: translate({ message: 'Kotlin' }), description: translate({ message: 'Apps written in Kotlin programming language', id: 'showcase.tag.kotlin.description', }), color: '#b125ea', }, + + webhook: { + label: translate({ message: 'Webhook' }), + description: translate({ + message: 'Apps exposing a Rest API, forwarding events inside Wire', + id: 'showcase.tag.webhook.description', + }), + color: '#25ea81', + }, }; export const TagList = Object.keys(Tags) as TagType[]; diff --git a/src/pages/support.md b/src/pages/contact.md similarity index 61% rename from src/pages/support.md rename to src/pages/contact.md index 1b2b1b8..b311d24 100644 --- a/src/pages/support.md +++ b/src/pages/contact.md @@ -1,3 +1,10 @@ +# Contact + +Apps are not yet a finalized product, you can create one with the SDK but you need a "demo" team to test. +In order to get one, please fill out: **[Demo team request](https://docs.google.com/forms/d/e/1FAIpQLSf2CvAxSLrfD_Mia1DD9WH_SV5iusVES5kjF84y2wExTMAuXg/viewform?usp=dialog)** + +If you are trying out the SDK or have already built one/multiple Apps, you feedback is greatly appreciated: **[SDK Feedback](https://docs.google.com/forms/d/e/1FAIpQLSeopiYlbfMMhBXb4A78xe1i9pX2HO7bYwAi48WS2qowQX8uyw/viewform?usp=dialog)** + # Support :::info @@ -14,7 +21,7 @@ Other developers can also join the conversation, which helps the whole community ## Before opening an issue -Please take a quick look at existing issues first: [https://github.com/wireapp/wire-apps-jvm-sdk/issues](https://github.com/wireapp/wire-apps-jvm-sdk/issues) +Please take a quick look at existing issues first: [Issues](https://github.com/wireapp/wire-apps-jvm-sdk/issues) Someone might already have asked the same question or shared a solution. If you find a related issue, feel free to add details or context there.