Webhooks¶

A webhook is a web address that one program calls to tell another that something happened. Ko-fi calls one when someone sends you a donation. A Stream Deck button can call one to run a macro. Home Assistant gives you one that turns on your lights. CroStream can be on either end:

flowchart LR
    K[Ko-fi, Stream Deck, Home Assistant, scripts] -- "incoming webhook" --> C[CroStream]
    C -- "Send a webhook" --> H[Home Assistant, a bot, your own server]

• Incoming webhooks are addresses on your PC that other apps can call. Each one turns what the sender posts into variables and fires a trigger, so a donation can thank the donor in chat, or a button press can switch scenes.
• Outgoing webhooks are the Send a webhook step in a macro. It posts text, JSON or a form to another system, and can turn the answer back into variables for the steps after it, so a raid can flash your room lights.

You don't need to know how HTTP works to use them. The editors show a ready-to-paste test command, a live preview of what your settings do, and a log of every call. Where something is technical, this page says so.

The Webhooks page¶

Open Webhooks in the sidebar, under Automate. It has two tabs: Incoming ("Other apps call CroStream") and Outgoing ("CroStream calls other apps").

The Incoming tab starts with the Listener panel (who can reach your webhooks, and the port), then lists your incoming webhooks. Each row shows:

• the name and its address;
• tags for how senders prove who they are (Token, HMAC signature, Token + HMAC or No check), how the body is read (Auto, JSON, Form or Text) and how many variables it maps;
• the status code and age of its last call, or Never called;
• a switch to turn it on or off. An off webhook answers 404, as if it didn't exist.

The Outgoing tab lists your destinations. The buttons New incoming webhook and New destination are at the top right.

Incoming webhooks¶

1. Choose who can reach the listener¶

CroStream answers incoming webhooks with a small web server of its own, the listener. It is separate from the one used for logging in to Twitch, and it only runs while at least one incoming webhook is turned on. Its panel on the Incoming tab sets two things:

The panel's status line says what is happening, such as listening on port 62690 (this computer only), or the error if the port can't be opened ("cannot listen on port … is another program using it? choose another port"). CroStream tries again every 30 seconds. After you change either setting, click Apply; Revert drops the change.

The three choices:

Below the choices, Addresses lists the base addresses you can use: always http://localhost:<port>, plus this PC's network addresses when the listener is exposed. Copy copies one.

Choosing a wider setting is refused while any webhook has No check (see Security): give it a token first.

2. Create a webhook¶

1. On the Incoming tab, click New incoming webhook.
2. Give it a Name (for example Ko-fi donations). It is what you pick in a trigger and what shows in the activity feed. Names must be unique.
3. The Address fills in from the name: the part after /hook/. Use 1 to 64 lowercase letters, digits and dashes, starting with a letter or digit, such as ko-fi. The full address is shown below it, with a Copy button. If the listener is exposed, the other addresses are listed under it.
4. Choose the Body format and the Methods (below).
5. Choose how senders prove who they are, under Security.
6. Click Create. The secrets are made when you save.

The On switch at the top of the Address panel turns the webhook on and off.

Body format tells CroStream how to read what the sender posts:

Methods are the HTTP methods the webhook accepts: POST (the default), PUT, PATCH and GET. At least one stays selected. Any other method gets 405. A GET has no body, so use the address's query for data: {query.scene} for ?scene=intro.

3. Choose how senders prove who they are¶

Anyone who knows an address can try calling it, so each webhook checks its callers. Under Security, Check has these choices:

The token and signing key are long random secrets, made when you save. Under Security each one is hidden behind dots, with three buttons:

• Reveal shows it, and Copy copies it to the clipboard.
• Regenerate makes a new one. The old one stops working at once, so update the sender straight afterwards. The button asks you to confirm.
• With a signing key there is also Use the service's key, for when the service generates the key and you must paste it in. For HMAC, set the Signature header to the name the service uses (for example X-Hub-Signature-256 for GitHub). The default is X-Signature-256.

Secrets are not kept in the settings file, only in CroStream's secrets store, and they are never exported or written to the log. Treat them like passwords.

4. Try it¶

The Try it box under Security writes the exact command for this webhook: curl for bash, or PowerShell. It already holds the right method, headers, a signature for HMAC webhooks, and your sample body. The token is shown as dots until you click Show secrets; Copy copies the real command, secrets included. For services that can only call a URL it also shows the address with ?token= and its own Copy.

Open a terminal on this PC, paste, and press Enter. The call appears under Recent deliveries at once. Or skip the terminal and click Send test there: CroStream makes the call to itself, signed and authorized like a real one, with your sample.

5. Turn the body into variables¶

A webhook that only fires isn't very useful. Usually you want what's in the body: who donated, how much, which button. The Variables panel turns values from the body into {variables} your macro can use.

1. Get a sample. Paste a body into Sample body (JSON, a form such as name=Ann&amount=5, or text), or pick Use a recent delivery… after the sender has called once. Start from an example… at the top right loads a typical one: a Ko-fi donation, a Companion or Stream Deck button, or a merch order. The panel says how it was read (JSON, Form or Text) and shows the size. Edit sample changes it, and Tidy re-indents JSON.
2. Click a value in Fields. It becomes a variable: CroStream suggests a name from the field, and picks the type from the value. Values already mapped show their variable next to them.
3. Adjust the rows under Variables. Each row is one variable:

Types in short:

• Text accepts any single value: numbers and yes/no values are written as they appear.
• Number accepts numbers and numeric text. Ko-fi's "5.00" stays 5.00; nothing is rounded.
• Yes / no gives true or false, from a real boolean, 0/1, or text such as yes, no, on, off.
• JSON writes whatever is there (an object, a list, any value) as compact JSON text. It's the only way to read an object or a list whole.

A value that is missing, or null, gives the row's If missing value (empty if you set none). A value of the wrong kind (text where a number was expected) also gives it, and the row shows what went wrong. A row with a default set doesn't complain about missing values: the default says it's optional.

What happens on a real call is exactly what the panel shows: the preview and the delivery use the same code, so the Value in sample column is what your macro will get.

Always set. Every call also sets these variables, whatever the format or mapping:

Query and header variables hold at most 4 KiB each, and at most 64 of each are set. A text webhook maps nothing: its variables get their If missing values.

6. Choose the reply¶

The Reply panel sets what the sender gets back once its call is accepted:

The body can use the webhook's {variables}: {"thanks": "{donor|json}"}. For a JSON reply, put values inside quotes with the |json filter (see Variables), so a quote or line break in them can't break the JSON. If the reply still isn't valid JSON once the variables are filled in, the call fails with 500 reply failed, and the trigger does not fire.

The reply is sent at once; it does not wait for your macro to finish.

7. Run a macro when it's called¶

Nothing happens on a call until a trigger listens for it.

1. On the webhook's page, click Use in a trigger. CroStream creates a trigger and a macro with a placeholder step, and opens the macro for you to replace the step with what should happen. (Once a webhook has triggers, the page lists them under Runs, with Another trigger.)
2. Or build it yourself: on the Triggers page, click New trigger, pick the event A webhook is received under Webhooks, and choose the Webhook.

The macro gets every variable from the table above and every variable you mapped; the trigger editor lists them. {detail} is a short summary, such as Ko-fi received (748 bytes). A webhook is caused by no viewer, so the trigger's Minimum role always passes, and {user} isn't set (map a {user} yourself if the body names someone, or use another name like {donor}). A Cooldown on the trigger works, and is a good way to protect against a sender that calls too often. Test on the trigger runs the macro with the webhook's saved sample, mapped by its rules.

Recent deliveries¶

Every call a webhook answers is logged under Recent deliveries, live, for the last 20 calls. The log is kept until CroStream restarts.

Each row shows the status code and its name, the method, a Test tag for calls from Send test, an orange count when some mapping had a problem, a red Error tag when the call failed, the sender's address, the body size and how long ago. Click a row to open it:

• Variables: what the macro got. Problems lists the rules that didn't work and why.
• Body: what was sent, with its content type, and Use as sample to map from it. At most 8 KB are kept. For a call refused for a wrong token or signature, the body is not kept.
• Answered: the reply that was sent.
• For a failed call, the reason, in words.

Only calls that got as far as the webhook are logged: ones refused before that (403, 404, 405 and 429, below) leave nothing here. A webhook that's off shows This webhook is off: calls get 404.

What the sender gets back¶

CroStream checks in this order: who is calling (403), the address (404), the method (405), the rate limit (429), the body size (413), and then the token or signature (401). So a call with a wrong token still counts against the rate limit, which makes guessing slow.

Rate limits¶

Each webhook limits how often it answers, to protect your stream from a flood or a runaway script:

• Each sender (by IP address; for IPv6, all addresses of one /64 count as one sender) may make 10 calls at once, then one every 2 seconds (30 a minute).
• Each webhook, from all senders together, may take 60 calls at once, then two a second (120 a minute).

Over the limit, the answer is 429 with a Retry-After header. A well-behaved sender waits and tries again. Calls through a tunnel or proxy on this PC all come from this PC, so they share one sender's limit.

Other limits: a body is read up to 1 MiB; at most 100 incoming webhooks and 100 destinations; at most 100 mapping rules per webhook; samples and replies up to 64 KiB.

Putting a webhook on the internet¶

Services like Ko-fi call you from the internet, so they need an address that reaches your PC. Two ways:

1. Port forwarding. Set Accept requests from to Open to all, and forward the port from your router to this PC. Give the service http://<your public address>:<port>/hook/<name>. Your home address usually changes, and plain http:// can be read by anyone on the path: the token travels in the clear. Many services refuse non-HTTPS addresses.
2. A tunnel (Cloudflare Tunnel, Tailscale Funnel, ngrok and similar), or a reverse proxy with a certificate. The tunnel gives you an https:// address and forwards to http://localhost:62690. This is usually the better way: no router changes, and the secret is encrypted on the way.

Whichever you pick:

• Prefer HMAC signature if the service offers it.
• With a tunnel or proxy on this PC, the listener sees every call as coming from this PC, so even Localhost only lets tunnel traffic in. The exposure setting can't protect you then; the token or signature does. And never use None with a tunnel.
• Forward only this port, and only while you need it.
• If a token ever leaks, Regenerate it.

The Ko-fi tutorial walks through a complete example.

Outgoing webhooks¶

Destinations¶

A destination is a place CroStream sends to, saved once: its address, how to sign in, and any fixed headers. Macros then pick it by name, so a token lives in one place and not in every macro.

On the Outgoing tab, click New destination:

Authentication choices:

Secrets are write-only. After you save, the editor shows dots and Saved; you can Replace or Remove the secret but never read it back. It lives in the secrets store, not in config.json, and isn't exported or written to the log. A destination whose secret is missing fails at send time with a message saying so.

Test sends one request right now, with the saved settings, and shows the answer: status, content type, body and how long it took (in milliseconds). Choose the method, an optional path added to the base URL, and a body (JSON, Text or No body). It is a real request; the answer to an error such as 404 is shown, not hidden. A test doesn't retry. Unsaved changes aren't used.

You can't delete a destination while a macro uses it: CroStream names the macros so you can change them first.

The Send a webhook step¶

In the macro editor, find Send a webhook in the palette under Webhooks.

Body choices:

JSON fields¶

The json body is a list of fields. Each has a Key (where the value goes), a Type and a Value.

The Body preview under the fields shows the JSON the step will build, and Valid JSON when it works. A problem, such as two fields that want the same key, is shown on the field. Variables the macro fills in later show as written in text fields; in number, yes/no and JSON fields the preview shows a stand-in (0, false or null) with a note on the field. Text values are escaped for you: a quote or a line break in {message} can't break the JSON. Fields run in order, and the keys of an object come out in the order the fields created them. The JSON paths reference lists every key form.

Writing the JSON yourself¶

With json_raw you write the whole body. Variables inside it are put in as they are, so put them inside quotes with the |json filter:

{"text": "{message|json}", "viewers": {viewers}}

{message|json} escapes quotes, backslashes and line breaks, so a chat message can't break your JSON. A number like {viewers} goes in bare. After the variables are filled in, the result is checked, and the step fails with the line and column of the problem if it isn't valid JSON.

Read the answer¶

Read the answer turns a JSON answer into variables for the steps after it. It works like the incoming webhook's Variables panel: rows of Variable, Read from (a path), As and If missing. Paste a Sample response to click values from, if you like. Every row sets its variable; a value that is missing, or an answer that isn't JSON, gives the row's default.

What the step reports back¶

The Activity page shows each send as, for example, POST homeassistant.local:8123: 200. Only the host is shown: headers, secrets and bodies are never logged.

Share and back up webhooks¶

Webhooks are part of your settings, so they are in backups and can be exported and imported with macros and triggers, with some care taken for secrets:

• Export (Settings → Export & import) lists Incoming webhooks and Webhook destinations, and has a Webhook listener settings box (who can reach them, and the port). A trigger brings its webhook, and a macro brings the destinations it uses.
• Never exported: tokens, signing keys, destination secrets, and the captured sample body (which can hold a sender's data).
• On import, incoming webhooks arrive turned off, with new tokens. Destinations arrive without their secret. An import never makes the listener wider than it is now: if the file allows more than your current setting, yours stays and a note says so. A webhook that had None gets a token if the listener isn't local.
• After an import, a Do this now box lists what to redo: turn the webhooks on, copy new tokens into the sender, enter destination secrets.

Backups and restores keep the webhooks' settings. If a restore brings back a webhook whose token was deleted with it, CroStream makes a new token, so copy it into the sender again. Destination secrets aren't part of a backup either: they stay where they are.

Security¶

Webhooks open a door into your stream, so here is exactly what protects it and what doesn't.

• The listener only runs while a webhook is on, and it is a separate server from the one that does the Twitch login, with strict timeouts, a 1 MiB body cap and rate limits.
• Each webhook has its own secret. A wrong token or signature gets a bare
• Tokens are compared in constant time, and the signing key is never sent.
• Unknown and turned-off webhooks answer the same 404, so a scanner can't learn which addresses exist.
• Who may connect follows the exposure setting, judged by the connection itself and never by forwarding headers. A proxy or tunnel on the same PC makes everything look local.
• Secrets stay out of files and logs. Tokens, signing keys and destination secrets are in the secrets store, and are not exported. The request's Authorization and Cookie headers and signature never become variables.
• Plain HTTP is readable. The listener speaks HTTP, not HTTPS. On your own PC or network that is fine. Across the internet, put a tunnel or proxy with a certificate in front.
• A token in an address (?token=) can end up in the logs of the sender and of anything in between. Use a header, or HMAC, if you can.
• In browser mode the HTTP API has no login and can read a webhook's token, like everything else in your setup. Keep it on your own PC or network, as that page says.

A good setup for most streamers: Localhost only for tools on your PC; Local networks only for a Stream Deck or Home Assistant; Open to all (through a tunnel, with HMAC or a token) only for services that must call you from the internet.

Troubleshooting¶

Related¶

• JSON paths and mapping: every path form, with examples.
• Events and Actions: the reference.
• Variables: the |json and |url filters.
• Triggers and Macros.
• Tutorials: Thank Ko-fi donors in chat and Flash your lights on a raid.
• Backups, export and import.