Manage an app

For org owners and admins

Each app has its own page, where org owners and admins change what it may do, connect its webhook, look after its token and signing secret, and see what it has been doing. Like creating an app, every change here needs your two-factor code and the desktop or web app. See Create an app.

Open an app’s page#

Open Settings → Integrations → Apps and select the app. The list shows each app’s status (Active, Paused, Turned off) and how many channels it’s in.

You can also select an app’s name or picture in any conversation and choose Settings on its card.

Name, picture, permissions and events#

Name and picture: change the name and description, Change picture or Remove picture, and select Save.
Permissions and events: tick what the app may do and the events it hears about, then select Save permissions. Changes take effect at once.
Who adds it to channels: Members or Admins only.

Letting an app read messages#

When you give an app Read messages, the app first asks Let Deploybot read messages?: “Deploybot will read every message in the channels it is in, earlier messages too.” It lists the private channels the app is in that you’re in, and counts the ones you’re not in.

In the private channels the app is already in, it reads messages only after a member of each channel allows it. That way, nobody can read a private channel they aren’t in through an app. The app’s page shows Waiting for a member to confirm in 2 private channels and Refused in 1 private channel until members answer. See Apps in your channels.

How the app gets events#

Under How the app gets events, choose Webhook or Polling. A polling app needs nothing else; the page shows when it Last polled.

The webhook URL#

A webhook app needs a public address that receives its events. Your developer runs the app there first, with its signing secret, because buildIt.social checks the address with a signed request the app must answer.

Enter the Webhook URL, such as https://example.com/buildit/events. It must be HTTPS on port 443.
Select Verify. buildIt.social sends the URL a signed check, which it must answer within 5 seconds.
When it answers correctly, you see The webhook URL is verified. Events go there from now on.

If the app has no signing secret yet, Verify offers to make it first. If the check fails, Not verified: says why, such as “we couldn’t reach the URL.” or “it answered, but not as the check expects”. Until a URL is verified, no events are sent.

Signing secret#

The app uses its signing secret to check that each event really comes from buildIt.social.

Make secret if the app doesn’t have one.
Rotate to get a new one, for example if it may have leaked. The new secret signs at once, and you choose how long the old one keeps signing beside it while your developer updates the app: 1 hour, 24 hours or 7 days.

The new secret is shown once. Copy it straight into the app’s settings.

Tokens#

The app calls the API with its token. Tokens never expire on their own. Each token shows when it was made and last used, and the last 4 characters as Token ending so you can tell them apart.

Make token if the app has none.
Rotate gives you a new token, shown once. The old one keeps working for 1 hour, 24 hours or 7 days while you update the app, then stops. At most 3 tokens can work at once.
Revoke stops a token at once. This can’t be undone.
A token unused for 90 days is Suspended, and owners and admins get a notice in the Inbox of the Work section. Select Resume to make it work again, or rotate it.

Tip: Rotate the token and the signing secret at once if either may have leaked, and revoke the old token if you don’t need the overlap.

Deliveries and API calls#

Deliveries (last 14 days) lists each event sent to the app with its type, status (Waiting, Delivered, Failed, Dropped), tries and any error, and when it last delivered. Filter by status. Select Send again on a failed event to retry it. The log never shows the events’ content.
API calls lists the app’s recent calls to the API with their result.

An event that fails is tried again 7 times over about a day. Events that wait more than 3 days are discarded.

When an app is paused#

buildIt.social pauses an app, and tells owners and admins in the Inbox of the Work section, when:

its webhook keeps failing for a day: Paused: deliveries are failing. Fix its server, then select Resume.
a polling app hasn’t polled for 7 days: Paused: not polled for 7 days. Resume it when it polls again.

While paused, the app’s token is refused and it gets no events. Its cards still record answers.

If an app has too many events waiting, new ones are dropped and owners and admins get a notice, at most once an hour.

Turn off or delete an app#

Under Turn off or delete:

Turn off: the app’s token is refused and it gets no events until you select Turn on. It stays in its channels, and its cards keep their answers.
Delete: the app leaves every channel it’s in, its tokens stop working, its signing secret is deleted and waiting events are dropped. Its messages stay, under its name. This can’t be undone.

Below your own apps, Provided by buildIt.social lists apps buildIt.social manages, such as buildIt.social Feedback. They can’t be edited, given tokens or deleted, and they don’t count toward your 10 apps.

The Feedback app’s row has a switch. Turning it off asks first: “The channel is archived and nothing more is sent to buildIt.social. You can turn it on again.” See Send feedback to buildIt.social.