# 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.

Canonical page: https://themachine.myapps.ai/docs/desktop/integrations/secrets-and-webhooks

## 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_KEY` or
`OPENWEATHER_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

![A bot's Secrets section, with a shared secret and one marked Only you](/images/docs/desktop/secrets.webp)

| 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](/docs/desktop/models/approvals#what-needs-your-ok).

Webhooks are created and changed on the Machine web app.