Skip to content

Secrets and webhooks

Things Alfred builds for you often need to talk to other services. Two pieces cover the two directions:

  • A secret is another service’s key or token (a Steam API key, a weather service’s token) that your code needs to call that service.
  • A webhook is a URL a service calls when something happens on its side (a GitHub push, a Stripe payment, a sensor reading), which wakes your automation.

Neither one goes through a conversation, and Alfred never sees what’s in either.

Never paste a key into a chat. When a build needs one, Alfred makes you a secret place: a small private page, at its own address, with one box for the key and the exact hosts it will be sent to (“only ever sent to api.steampowered.com”). Only you can open it, signed in.

Paste the key there and press save. The page says it’s saved, and when, and never shows the key again, not even to you. Alfred learns that it’s set and nothing more: the key isn’t in the page, the chat, the activity log, or anywhere he can read.

You can just ask for it: “I’ve got a Steam API key, set it up so the game tracker can use it”.

Code that needs the key names it by a placeholder, and the key is filled in on the way out by the sandbox’s proxy, outside the code’s reach. It’s only ever sent to the hosts the page showed you, and if the service echoes it back in an answer, it’s blanked out before the code sees it. So neither the code, Alfred, nor anything that tricks either of them can read the key or send it anywhere else.

If the hosts need to change, Alfred updates the page, and the key only goes to the new hosts once you’ve entered it again there. That way nothing, Alfred included, can widen where a key goes without you seeing it.

A key acts on another service as you, so it’s only used in your own private work:

  • Never from a channel other people can read, such as a Discord server.
  • Never in a test run. Alfred tests a reflex before saving it, and that test gets no keys.
  • Never from work a stranger set off: a visitor’s submit on one of your places, or a webhook delivery.
  • Inside a job, code that uses a key counts as acting outside the job, so it’s decided by the job’s autonomy like sending a message would be.

When a key is used with nobody watching (by a reflex, a job or a background agent), it’s on your activity log.

PlanSecretsEach up to
Free52 KB
Power208 KB
Power+408 KB
Elite6016 KB
Elite+10016 KB

Ask Alfred which secrets you have and whether each is set. Deleting the secret place leaves the secret, since code may still be using it; ask him to delete the secret itself when you’re done with it, and revoke the key on the other service too if it might have leaked anywhere else.

A webhook is an address on Butler that a service of yours sends to. Ask for one by saying what will call it: “give me a webhook for my GitHub repo’s pushes”, “Stripe should tell you when someone pays”.

There are four kinds, and Alfred picks the one the sender supports:

KindFor
GitHub-styleGitHub, and most services that sign their deliveries with a shared secret.
StripeStripe, which issues its own signing secret. You enter it on a secret place.
Your own codeApps you or Alfred write, signed with the SDK.
TokenA sender that can’t sign anything, such as a sensor or a form service. The URL itself is the password.

The URL and its secret are shown once, in the reply that made them, for you to paste into the sender’s settings. They aren’t kept anywhere you can read again. If you lose them, ask Alfred to rotate the webhook: you get a new one, and the old one stops working at once.

A delivery that checks out becomes an event, which does nothing until something listens:

  • A reflex listening to the webhook runs on it, which is the usual way to act on one (“when Stripe says someone paid, add them to the customers list”).
  • A watch wakes a conversation with it.

A webhook never starts a chat by itself. Senders retry, so a delivery sent twice is taken once. A delivery that doesn’t check out is refused and costs you nothing.

What a sender posts is a stranger’s words, so Alfred treats it as information, never as instructions, and work it sets off never gets your keys.

Each webhook takes up to 60 deliveries a minute, each up to 64 KB.

PlanWebhooksDeliveries a day
Free2500
Power105,000
Power+2020,000
Elite4050,000
Elite+60100,000

Past either limit the sender is told to try again later. Ask Alfred to list your webhooks to see what each one has taken and refused, or to delete one.

Secrets, webhooks and API keys are refused in a channel other people can read. Ask about them in a DM or on the Dashboard.