Secrets and webhooks
Give a bot the API keys and passwords it needs, safely, with write-only secrets, and see the webhooks that can start a bot.
Secrets
A secret is an API key, token, or password a bot needs, like a Stripe key or a database password. Secrets are stored so that nobody can read them back, not even you, and they never appear in the conversation.
The bot's computer gets each secret as an environment variable: a named value that programs can read. When the bot runs code that needs the key, the code finds it there.
Never paste keys into the chat
Anything you type in a message stays in the conversation, where anyone who can see the thread can read it. Always add keys as secrets instead.
Add a secret
Open Secrets
Open the bot's settings (click its name in the chat header) and go to Secrets. The page says these are "API keys and tokens this bot's computer gets as environment variables. Values are write-only."
Click Add secret
Fill in:
- Name: in capitals with underscores, like
STRIPE_API_KEYorOPENWEATHER_KEY. - Value: the key itself. It's shown once, while you type, and never again.
Choose who it's for
Tick Only for me if this is your personal key, used only when you run this bot. Everyone else keeps the shared value.
Leave it unticked to share the value with everyone who uses this bot.
Tell the bot
Let the bot know the secret exists:
I've added our Stripe key as the secret STRIPE_API_KEY. Use it to list last month's payments.
Badges
| Badge | Means |
|---|---|
| Only you | Your personal value for this secret. |
| Managed | Provided by Machine. You can't change it. |
| Shared | Everyone who uses the bot gets this value. |
| No value | The name exists but no value is set. |
If a secret shows a not delivered warning, the bot's computer hasn't received it yet.
Change or remove a secret
To remove a secret, click Remove next to it and confirm. To change a value, remove the secret, then add it again with the same name.
Where to get keys
Each service has its own place for keys, usually in its Settings, Developer, or API section. Search the service's help for "API key". Use the most limited key the job needs, and remove it when you're done.
Webhooks
A webhook is a way for another service to start a bot automatically. For example, a form tool could start a bot every time someone submits a form.
To see the webhooks that start a bot, open its settings and go to Access → Webhooks. Each shows its name, whether it's Active or Paused, and how many times it has been triggered (its deliveries). If there are none, it says No webhooks for this bot.
A webhook starts the bot without you there, so it's worth setting What needs your OK with care for bots that webhooks can start. See Approvals.
Webhooks are created and changed on the Machine web app.