Inbound Webhooks

Inbound webhooks let external systems send Voice Monkey an HTTP request, which triggers an action of your choice. Use them to fire announcements, trigger routines or start Flows from anything that can make an HTTP call — IFTTT, Home Assistant, Flic, custom code, etc.

The feature is called “inbound” because the request comes into Voice Monkey. (Outbound calls — where Voice Monkey makes HTTP requests out to other services — are handled by the Web Request node in Flows.)

Create an inbound webhook

1. In the console, go to Inbound Webhooks and click Create Inbound Webhook.
2. Give it a name. As you type, the form shows the slug that will be used in {WEBHOOK.<slug>.<key>} references (e.g. Front Door → FrontDoor).
3. Add one or more actions to fire when the webhook is hit:
   • Announcement — make a TTS announcement on an Alexa speaker.
   • Routine Trigger — trigger a Voice Monkey Routine Trigger device (which in turn fires an Alexa Routine).
   • Flow — start a Flow (the inbound webhook is recorded as the source in the activity log).
4. Click Create Inbound Webhook to save. You’ll be taken to the edit page where you can copy the unique webhook URL.

Call the webhook

Send a POST or PUT request to the URL. The body fields are stored against the webhook so you can reference them in actions and Flows.

curl -X POST https://api-v3.voicemonkey.io/catch/USER_ID/WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"room":"living room","status":"motion"}'

JSON, application/x-www-form-urlencoded and multipart/form-data bodies are all supported, as are query-string parameters (?room=kitchen). A request with no body still fires the actions; the payload simply stays empty.

Tip

Opening a webhook URL in a browser (a plain GET) returns a friendly help page rather than a 405, so you can paste the URL anywhere safely without leaking what it does.

Use payload values

Reference payload values with {WEBHOOK.<slug>.<key>} in any speech text, action parameter or Flow node.

Motion detected in {WEBHOOK.FrontDoor.room}

The slug is the webhook’s name converted to PascalCase — e.g. a webhook named Front Door has slug FrontDoor. The console shows the exact slug on the Inbound Webhooks list and on the edit page, right under the Name field.

Every inbound webhook also shows a Recent Payload panel listing the keys from the most recent request, each with a one-click copy for its full variable reference. Hit Refresh to fetch the latest data after firing a test request.

The same {WEBHOOK.<slug>.<key>} syntax works everywhere — inside a webhook’s own actions it resolves against the current request; anywhere else it resolves against the most recent stored payload.

Limits

Payload size

• Request body: max 64 KiB. Larger bodies are rejected with a 413 before they’re parsed.
• Stored payload: capped at 8 KiB per webhook with individual values truncated at 512 characters. The cap is applied during storage and doesn’t affect what’s passed to the webhook’s own actions on the firing request — it only limits what’s available for later reference through {WEBHOOK.<slug>.<key>} in Flows.

Plan limits

• Free: 2 inbound webhooks.
• Hobby: 10 inbound webhooks.
• Ultimate: unlimited inbound webhooks.