HTTP
Included with Macro DeckSend HTTP requests from a button and save values from the response into variables.
The HTTP integration page with the switch turned on and no configuration options
- GET, POST, PUT, PATCH, DELETE and more, with query and headers
- Basic, bearer token or API key header authentication
- JSON, form, text and file upload bodies
- Save the status, headers or JSON values into variables
- Variables in the values of query parameters and headers
The HTTP integration sends web requests from Macro Deck. Use it to call a webhook, control a device on your network that has a web API, or read a value from an online service and show it on a button. It comes with Macro Deck and is turned on from the start, so there is nothing to connect or sign in to.
Two actions
Send HTTP Request builds a full request. You choose the Method, enter the URL and add Query parameters and Headers as name and value pairs. Under Body type you pick none, json, form, text or multipart (a file upload with extra form fields). Authentication offers basic (username and password), bearer (a token) and header (a token in a header you name, for example X-Api-Key). Expected status decides which answers count as success, 2xx by default. You can also set the Timeout, turn off Follow redirects and limit the Max response size (bytes).
Captures save parts of the response into variables. Each line pairs a variable name with a selector: $status, $ok, $duration, $body, $truncated, $headers, $header:<name> or a JSON path such as data.items[0].name. A variable that does not exist yet is created.
Get JSON Value is the short form for reading one value: enter the URL, a JSON path and the variable under Save to variable.
Example setups
- A button that posts
{"text": "Stream is live"}to a chat webhook with Send HTTP Request and body typejson. - A button that turns on a smart plug on your network through its local web API.
- A button that reads the current price from a public API with Get JSON Value and shows it in its label with
{{ vars.price }}. - A flow that sends a request, captures
$statusand uses If / Else to color the button red when the server did not answer with200.
The values of query parameters and headers can contain variables, for example {{ vars.channel }}. The request runs on the computer where Macro Deck runs, so addresses like http://192.168.1.20 reach devices in that computer's network. An action fails with a clear message when the server cannot be reached, the request times out, the TLS certificate is rejected or the status is not the one you expected.
What you need
- Macro Deck 3 on Windows, macOS or Linux
- The address of the web API or webhook you want to call
- An API key, token or password, if the service needs one
Set it up
Step 1: Check that the integration is turned on
In Macro Deck, click Integrations in the sidebar and click HTTP. The switch at the top right is on by default; turn it on if it is off. There is nothing to set up: the Overview tab shows No configuration options available for this integration.
Step 2: Add an HTTP action to a button
On the Deck page, click a button. The deck must be unlocked: when the Lock button shows at the top right, it is. The editor opens with Short Press selected. Click + Add action, select HTTP on the left of the Add action dialog and pick Send HTTP Request, or Get JSON Value if you only want to read one value. You can also type the name into Search actions....
Step 3: Enter the request
Choose the Method and enter the URL. Add Query parameters and Headers if the API needs them. For a request with data, pick the Body type and fill in the JSON body, Form fields or Text body.
Step 4: Add authentication
If the service needs a login or key, choose it under Authentication:
basicwith Username and Password / token,bearerwith the token in Password / token, orheaderwith the Header name and the key in Password / token. Most services show their API keys or tokens in their account or developer settings.Step 5: Save values from the response
To use the answer, add lines under Captures: a variable name and a selector such as
$statusor a JSON path likedata.temperature. With Get JSON Value, enter the JSON path and pick the variable under Save to variable.Step 6: Try the button
Click Run in the editor to send the request right away, or save and press the button. If the action fails, its message tells you why, for example that the server could not be reached or the status did not match Expected status.
Actions2
Put these on a button or run them from a flow.
- Send HTTP Request
- Sends a configurable HTTP request and can capture the response into variables.
- Get JSON Value
- Fetches a URL and writes one value from the JSON response into a variable.
Frequently asked questions
Where are my API keys and passwords stored?
What you enter in Password / token is stored encrypted and is only turned into plain text when the request is sent. Values you type into Headers are stored unencrypted and travel inside exported profiles, so put keys and tokens in the authentication fields instead.
Can I call a device on my local network?
Yes. The request is sent from the computer that runs Macro Deck, so any address that computer can reach works. For a device with a self-signed certificate you can turn off Validate TLS certificate, but only do that for devices on your own network.
Why does the action fail although the server answered?
The answer did not match Expected status, which is 2xx by default. Enter the status code the API really returns, a range like 200-204, a list, or any to accept every status. Get JSON Value always expects a 2xx answer.
Which JSON paths can I use?
Use dots and indexes, for example data.items[0].name or [0].id, or $ for the whole document. In Captures, the reserved selectors such as $status come first, so a field that is really named status is read with $.status.
Do I have to create the variables first?
No. When a capture or Save to variable names a variable that does not exist, Macro Deck creates it. If a variable with that name already exists with a different type, saving fails with a message.
More in Smart home and web
Home Assistant
Included with Macro DeckSwitch lights, run scenes and scripts, and show live states from your Home Assistant on your deck.
AdGuard Home
Included with Macro DeckTurn AdGuard Home protection on, off or pause it, and show its statistics on your deck.
RSS feeds
Included with Macro DeckFollow RSS and Atom feeds, show their newest articles in widgets and react when new articles arrive.
Weather
Included with Macro DeckShow the current weather and the forecast for your locations on your deck, without an API key.