Integrations

An integration (an app) posts to channels as a bot with its own name, description, and icon. Apps are how you wire Sangria to your other tools — alerts, deploy notices, ticket updates — and how those tools react to what happens in chat. Only admins manage integrations, in Customize workspace → Integrations.

What an app looks like

Each app has a name, a description, and an icon, and it posts as a bot rather than as a person. Hovering an app's name anywhere in Sangria shows a card describing it and listing the channels it posts to.

Adding or removing an app from a channel posts a system message in that channel, so members can see when a bot joins or leaves.

Incoming webhooks

An incoming webhook lets another tool push messages into Sangria.

1. Add the app to a channel. Each app gets a webhook URL per channel it's added to.

2. Have your other tool send an HTTP POST to that URL with a JSON body:

   { "text": "Deploy finished — v2.4.1 is live" }

3. The message appears in that channel, posted as the bot.

This is a good fit for alerts from other tools — monitoring, CI, or a scheduled job that just needs to drop a line into one channel. Because the URL is tied to a single channel, you can add the app to more channels to get a separate URL for each.

Bot API token

An app also has a bearer API token. Use it to post to any channel the app is in, without a per-channel URL. Send a POST to /api/messages with an Authorization header and a JSON body naming the channel:

POST /api/messages
Authorization: Bearer <token>

{ "channel": "<name-or-id>", "text": "Backup completed" }

Outgoing event subscriptions

Event subscriptions let an app react to what happens in Sangria.

1. Give the app a public https URL to receive events. Internal or localhost addresses are rejected.
2. Choose the event types you care about — message and reaction.
3. Whenever a subscribed event happens in a channel the app is in, Sangria sends a signed JSON POST to your URL.

Your receiver should verify each request before trusting it:

• X-Webhook-Signature — an HMAC-SHA256 signature of the payload, computed with the app's signing secret. Recompute it and compare.
• X-Webhook-Timestamp — the time the event was sent. Check it alongside the signature when you validate the request.

Installing an OAuth app

Some apps are built by a developer to be installed into many workspaces, rather than hand-created in yours. You'll recognize these by an "Add to Sangria" link or button on the app's own site, rather than the create form above — or find one already inside Sangria, in Customize workspace → App directory, if its developer chose to list it there. The directory has a category filter (Productivity, DevOps, Communication, and so on) and shows how many other workspaces on this deployment already have an app installed; clicking a card opens a fuller view with the app's full description and exactly what it'll be able to do before you commit to installing it.

1. Click the app's install link (or a card's Install button in the app directory) — you'll land on a consent screen (still inside Sangria, not a third-party site).
2. If you're an admin of more than one workspace, pick which one to install into.
3. Review what the app will do — it always lists posting messages to a channel you choose, plus any events it's asking to receive (new messages, reactions, or button clicks) — then pick that channel.
4. Allow installs it (same as creating an integration by hand: a bot joins the channel, and the change is audited); Deny installs nothing.

An app installed this way shows an OAuth badge next to its name in Customize workspace → Integrations, and works exactly like any other integration from there — add it to more channels, regenerate its token to revoke access, or remove it entirely. Regenerating the token immediately invalidates the credential the app's developer was given; nothing else about how you manage it differs from an app you created yourself.

Exact request and response details

This page is the overview. For precise request and response shapes, headers, and signature verification, see the developer reference.