HudHud Cloud

Build on HudHud Cloud

One account and one access token for SMS, domains, DNS and storage — from your code or from an AI agent.

Quick start

  1. Create an account and set up SMS from the client portal.
  2. Create an access token in Developer cloud → AI & API access. Copy it — it's shown once.
  3. Send your first message:
export HUDHUD_TOKEN=hh_pat_…
curl /api/sms/send \
  -H "Authorization: Bearer $HUDHUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"2519XXXXXXXX","text":"Selam from HudHud"}'

Messages are charged to your SMS balance and follow your account's sender IDs, rate limit and daily quota — the same rules as the portal.

Authentication

Send a personal access token as a bearer token on every request:

Authorization: Bearer hh_pat_…

Tokens start with hh_pat_, carry a set of permissions, and expire after 30 days, 90 days, a year or never — you choose. HudHud stores only a hash of each token. Revoke a token from the console and it stops working immediately.

Access tokens work with the MCP server, the developer endpoints below, and POST /api/sms/send. Existing SMS API keys (hh_live_…, as X-API-Key or a bearer token) keep working for sending SMS.

Keep tokens on servers and developer machines. Don't put them in mobile apps or browser code — anyone who has the token can act on your account within its permissions.

Permissions

Give each token only what it needs. A token used by an AI agent to look things up should be read-only.

PermissionAllows
Loading…

Some actions are console-only and can't be done with a token at all: creating or revoking tokens, and connecting or disconnecting Cloudflare.

AI agents (MCP)

HudHud runs a Model Context Protocol server, so AI coding tools can use your account directly: send an SMS after a deploy, add a DNS record for a new subdomain, upload a build artifact, or check whether an invoice is paid.

Endpoint
TransportStreamable HTTP (POST, JSON responses)
AuthenticationOAuth 2.1 sign-in (discovered automatically), or an access token in the Authorization header

The agent only sees the tools its token allows — a read-only token gets no tools that change anything. Tools for SMS, orders, invoices and support follow the same rules as the portal: wallet billing, sender IDs, quotas and rate limits. Every tool call is written to your activity log with the token's name, so you can see exactly what an agent did.

Client setup

The quickest way: paste into your AI tool. It finds HudHud's sign-in automatically, opens a HudHud page where you choose permissions, and keeps itself signed in. There's no token to copy, and you can remove the app any time in Console → AI Agents.

ToolHow to connect
Claude (web, desktop, mobile)Settings → Connectors → Add custom connector → paste the URL → Connect.
ChatGPTSettings → Apps & Connectors → Advanced settings → turn on Developer mode → Create → paste the URL, authentication OAuth.
Claude Codeclaude mcp add --transport http hudhud-cloud , then /mcp → Authenticate.
Cursor~/.cursor/mcp.json: {"mcpServers":{"hudhud-cloud":{"url":""}}}, then click Needs login. The console also has an Add to Cursor button.
VS Code (Copilot).vscode/mcp.json: {"servers":{"hudhud-cloud":{"type":"http","url":""}}}, then start the server and sign in.
Windsurf~/.codeium/windsurf/mcp_config.json: {"mcpServers":{"hudhud-cloud":{"serverUrl":""}}}
Gemini CLI~/.gemini/settings.json: {"mcpServers":{"hudhud-cloud":{"httpUrl":""}}}, then /mcp auth hudhud-cloud.
Antigravity… menu in the agent panel → MCP Servers → Manage MCP Servers → View raw config. In ~/.gemini/config/mcp_config.json: {"mcpServers":{"hudhud-cloud":{"serverUrl":""}}} — use serverUrl, not url. Sign-in opens automatically.
LovableConnectors → Add custom → MCP server (older menus: Settings → Connectors → Personal connectors → New MCP server). Name HudHud Cloud, paste the URL, Add & authorize. Lovable uses it while it builds; it is never part of your published app.
Codex~/.codex/config.toml: [mcp_servers.hudhud-cloud] with url = "", then codex mcp login hudhud-cloud.

With an access token (CI, scripts, or tools that can't open a browser): create a token in the console, put it in HUDHUD_TOKEN, and send it as a header.

claude mcp add --transport http hudhud-cloud  \
  --header "Authorization: Bearer $HUDHUD_TOKEN"
// Cursor, Windsurf, Gemini CLI and most other clients
{
  "mcpServers": {
    "hudhud-cloud": {
      "url": "",
      "headers": { "Authorization": "Bearer ${env:HUDHUD_TOKEN}" }
    }
  }
}

For client developers: HudHud implements the MCP authorization spec. /mcp answers 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp". Authorization server metadata is at /.well-known/oauth-authorization-server, with dynamic client registration (RFC 7591), authorization code + PKCE (S256 only), resource indicators (RFC 8707), and refresh-token rotation. Access tokens last 1 hour; refresh tokens last 60 days. Reusing an old refresh token revokes the connection.

Tools

Tools that cost money or delete data are marked so the agent asks you first.

ToolWhat it doesNeeds
Loading…

AI agent guide

Everything you need to let Claude Code, Cursor, Codex, Antigravity, Lovable and other agents build and run things on HudHud safely. For agents reading this page: a plain-text summary is at /llms.txt.

1. Connect in five minutes

  1. Top up your wallet (Console → Wallet & usage). Servers and databases need at least a day of their price in the wallet.
  2. Set guardrails: how much per hour agents may spend, and whether they may delete, resize, restore or run commands.
  3. Open Console → AI Agents, pick your agent and paste its config (or the URL ).
  4. Sign in when the browser opens and choose permissions. Start with read-only and add write permissions when you need them.
  5. Ask: “What's running on my HudHud account and what does it cost?” The agent should call wallet_balance, servers_list and databases_list.

2. Permissions

Each connection or token only gets the scopes you approve. Tools the connection can't use are hidden from the agent.

ScopeAllows
Loading…

Recommended sets: looking around — every :read scope; deploying apps — add servers:write, databases:write, dns:write; marketing team — sms:read, sms:send only; CI — a token with sites:deploy only.

3. Guardrails

Guardrails apply to everything done with a token or a connected agent, never to you in the console. Only a console session can change them, so an agent can't raise its own limits.

SettingDefaultEffect
Max hourly spendETB 100/hourSum of the hourly prices of servers and databases created by agents and tokens. Creating, resizing or snapshotting beyond it is refused with agent_spend_limit.
Max resources5How many servers + databases agents may have at once (agent_limit).
Run commandsOnserver_run_command. Needed to deploy apps without SSH.
Resize / restore / deleteOnDestructive tools also require the exact resource name as confirm, so a typo can't hit the wrong server.

Agents can read the limits with agent_guardrails before they plan paid work. Every call is in the activity log; remove a connection in Console → AI Agents and it stops immediately.

4. Ready-made prompts

HudHud publishes MCP prompts. In Claude Code they appear as slash commands (/mcp__hudhud-cloud__deploy_app); other clients list them in their prompt menu.

PromptWhat it doesArguments
Loading…

5. Recipes

Deploy a Node or Docker app

You: Deploy github.com/acme/shop on a Pro Ubuntu server and point shop.acme.et at it.
Agent: agent_guardrails → cloud_catalog → (asks you to confirm ETB 6.41/hour)
       server_create {name:"shop-1", plan:"pro", image:"ubuntu-24.04"}
       servers_list (waits for "running")
       server_run_command "curl -fsSL https://get.docker.com | sh"
       server_run_command "git clone https://github.com/acme/shop /opt/shop && cd /opt/shop && docker compose up -d"
       server_firewall {enabled:true, rules:[22, 80, 443]}
       cloudflare_create_dns_record {type:"A", name:"shop", content:"<public IP>", proxied:true}

Give an app a database: database_create (private) → database_connection → write DATABASE_URL to .env → run migrations. The database firewall already allows your own servers.

Safe upgrade: snapshot_create “before-upgrade” → server_resize or run the upgrade → check server_metrics and the app → if broken, snapshot_restore (needs confirm) → snapshot_delete when happy (snapshots cost a little per month).

SMS campaign: sms_contact_lists → sms_templates_list → sms_quote → sms_create_campaign_draft with listIds. Drafts never send by themselves; with scheduleAt it sends at that time. Opted-out numbers are dropped automatically; afterwards read sms_campaign_report.

6. Troubleshooting

You seeDo this
401 / invalid_tokenThe sign-in expired or was removed. Reconnect (Claude Code: /mcp → Authenticate). Tokens: check it isn't expired or revoked.
“missing the … permission”Reconnect and tick that scope, or create a token that has it.
agent_spend_limit, agent_limit, “Guardrails”The account owner raises the limit in Console → AI Agents → Guardrails.
insufficient_balanceTop up; the response says how much is needed.
guest_agent_unavailableInstall qemu-guest-agent on the server (apt install qemu-guest-agent) or use SSH.
429120 MCP calls a minute per connection; 30 commands a minute per server. Wait a minute.
Server stays “Queued”In regions set up by hand, HudHud staff create it (usually within one business day). You aren't billed until it runs.
Antigravity: server not foundUse serverUrl in mcp_config.json, not url.

Cloud servers & databases

Linux servers and managed PostgreSQL, MySQL and MongoDB in Addis Ababa, billed per minute from your ETB wallet (charged hourly, capped per month). Every endpoint accepts a console session, an access token or an agent connection with the scope shown. Plans and prices: GET /api/cloud/catalog (public).

EndpointWhat it doesScope
POST /api/cloud/quotePrice a configuration (hourly, monthly cap, minimum balance)—
GET /api/cloud/overviewWallet, hourly burn, hours left, this month's spendaccount:read
GET|POST /api/cloud/serversList / create (name, plan, image, publicIp, extraStorageGb, sshKeys). Returns the password once.servers:*
POST /api/cloud/servers/:id/actions{"action":"start"|"stop"|"reboot"}servers:write
POST /api/cloud/servers/:id/execRun a command: {"command":"…","timeoutSeconds":60} → exit code, stdout, stderrservers:write
PUT /api/cloud/servers/:id/firewall{"enabled":true,"rules":[{"proto":"tcp","port":"22"}]}servers:write
GET|POST /api/cloud/{servers|databases}/:id/snapshotsList / take a snapshot; POST …/snapshots/:name/restore with confirm; DELETE …/snapshots/:name*:write
POST /api/cloud/{servers|databases}/:id/resize{"plan":"ultra"} — disks only grow; brief restart*:write
GET /api/cloud/{servers|databases}/:id/metrics?range=hourCPU, memory, network, disk (hour, day, week, month)*:read
POST /api/cloud/{servers|databases}/:id/credentialsPassword and connection string*:write
DELETE /api/cloud/{servers|databases}/:idDelete; body {"confirm":"<exact name>"}*:write
GET|POST /api/cloud/databasesList / create (name, engine, plan, publicAccess, trustedSources)databases:*
PUT /api/cloud/databases/:id/trusted-sourcesIPs or networks allowed to connect (your servers always are)databases:write
GET /api/cloud/usage?month=YYYY-MMPer-resource usage and chargesaccount:read
GET|PUT /api/cloud/agent-policyAgent guardrails (PUT from the console only)account:read
curl -X POST /api/cloud/servers \
  -H "Authorization: Bearer $HUDHUD_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"api-1","plan":"pro","image":"ubuntu-24.04","sshKeys":["ssh-ed25519 AAAA… me@laptop"]}'

SMS

Recipients use the international format 2519XXXXXXXX. HudHud detects Amharic automatically; you can also pass "language": "am" or "en".

LanguageOne SMSEach part of a longer message
English160 characters153 characters
Amharic70 characters67 characters

Price a message before sending with POST /api/sms/quote (no token needed). The full SMS reference — campaigns, bulk uploads and delivery history — is in the SMS API docs.

Cloudflare DNS

Connect your own Cloudflare account once in Developer cloud → Cloudflare DNS. HudHud never uses its own Cloudflare account for your domains.

  1. In Cloudflare, go to My Profile → API Tokens → Create Token.
  2. Use the Edit zone DNS template and pick the zones HudHud may manage. Add Zone → Cache Purge → Purge if you want cache purges.
  3. Paste the token into the console. HudHud checks it can list your zones, then stores it encrypted.

After that, your HudHud tokens with dns:read / dns:write can manage records:

# Point api.example.et at a server, proxied through Cloudflare
curl -X POST /api/cloudflare/zones/ZONE_ID/dns \
  -H "Authorization: Bearer $HUDHUD_TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"A","name":"api","content":"196.188.172.10","proxied":true}'

Supported record types: A, AAAA, CNAME, TXT, MX, NS, SRV and CAA. TTL is 1 (automatic) or 60–86400 seconds. Only A, AAAA and CNAME records can be proxied.

Object storage

Buckets are private. To move files in and out, ask HudHud for a short-lived signed link, then use it with any HTTP client — the file goes straight to storage without passing through your server.

# 1. Ask for an upload link (contentLength is the exact file size in bytes)
curl -X POST /api/storage/buckets/invoices/upload-url \
  -H "Authorization: Bearer $HUDHUD_TOKEN" -H "Content-Type: application/json" \
  -d '{"key":"2026/q3.pdf","contentLength":482113,"contentType":"application/pdf"}'

# 2. Upload, sending exactly the headers returned in step 1
curl -X PUT --upload-file q3.pdf \
  -H "content-length: 482113" -H "content-type: application/pdf" "$UPLOAD_URL"

# Download link, valid for an hour
curl -X POST /api/storage/buckets/invoices/download-url \
  -H "Authorization: Bearer $HUDHUD_TOKEN" -H "Content-Type: application/json" \
  -d '{"key":"2026/q3.pdf","expiresIn":3600}'

Upload links expire after 15 minutes by default (up to an hour) and only accept the exact size you asked for, so a link can't be reused to upload something larger than your quota allows. Single uploads can be up to 5 GB.

Bucket names are 3–40 lowercase letters, numbers and hyphens. Each account can have 5 buckets with quotas up to 100 GB each.

Direct S3 access keys for AWS SDKs, rclone and backup tools are coming next. Until then, use signed links.

Verify (one-time codes)

Send a one-time code by SMS and check what the user typed, with two calls. HudHud generates the code, keeps only a hash of it, expires it, limits attempts and blocks abuse. Each code SMS is billed like a normal SMS from your wallet or plan. You need a token with the verify:send permission; existing hh_live_ SMS API keys also work.

# Send
curl -X POST /api/verify/send \
  -H "Authorization: Bearer $HUDHUD_TOKEN" -H "Content-Type: application/json" \
  -d '{"to":"251911234567","appName":"My Bank","language":"en","codeLength":6,"ttlSeconds":600}'

# Check
curl -X POST /api/verify/check \
  -H "Authorization: Bearer $HUDHUD_TOKEN" -H "Content-Type: application/json" \
  -d '{"id":"vf_…","code":"483920"}'
# {"id":"vf_…","status":"approved","valid":true}
FieldMeaning
toEthiopian mobile number, 2519XXXXXXXX, +2519… or 09…
appNameName shown in the message (up to 30 characters)
languageen (default) or am
codeLength / ttlSeconds4–8 digits (default 6); 60–1800 seconds (default 600)
templateOptional custom text with {code}, {app}, {minutes}
senderOptional approved sender ID

Rules: a code works once and allows 5 attempts. Sending a new code to the same number cancels the previous one. At most 5 codes per number per 10 minutes. Codes are masked in your SMS history. Check by id, or by to to check the latest code for a number. Always branch on valid, not on status. Other calls: GET /api/verify/{id}, POST /api/verify/{id}/cancel, GET /api/verify (recent codes and 30-day stats). Webhook events: verify.approved, verify.failed.

Apps (deploy servers from GitHub)

Apps run your backend or full-stack code: a Next.js or Express server, a Django or FastAPI API, a Laravel site, a Go service, or a background worker such as a Telegram bot. HudHud builds a container from your repository, starts it in Addis Ababa and gives web apps https://<name>.run.hudhudexpress.com with HTTPS. Use Sites instead for static front-ends.

  1. Open Console → Apps and press New app.
  2. Paste the repository (owner/repo). Public repositories work as they are; for private ones, connect GitHub with a fine-grained token (Contents and Metadata read, Webhooks read and write).
  3. Pick a plan, optionally a database and Redis, add environment variables and press Create and deploy. Follow the build log live.

Every push to the app's branch builds and deploys automatically. A new version only replaces the old one after it has started and stayed up; if it crashes or fails to build, the previous version keeps serving. Any earlier version can be put back with Roll back without rebuilding.

Your app must listen on $PORT (8080 unless you set another port) and on 0.0.0.0, not localhost. HudHud also sets HUDHUD_APP, HUDHUD_COMMIT and, with add-ons, DATABASE_URL and REDIS_URL.

Plans and billing

Paid plans are billed per minute from your ETB wallet, charged hourly, and never more than the plan's monthly maximum. The Free plan gives one app that sleeps after 30 minutes without traffic and wakes on the next visit (the first request takes a few seconds); its database is limited to 512 MB. If the wallet runs out, paid apps are paused (data is kept) and restart automatically after a top-up. Current prices are on the plan cards in the console and at GET /api/apps/catalog.

Supported stacks

Detected fromStackDefault start
DockerfileYour own image (always wins)Your CMD
package.json with nextNext.jsnext start -p $PORT
package.jsonNode.js / Express / NestJS / SvelteKit / Bun (npm, pnpm or yarn)npm start
manage.pyDjangogunicorn <project>.wsgi
requirements.txt / pyproject.tomlFastAPI, Flask or plain Pythonuvicorn / gunicorn / python main.py
composer.json + artisanLaravel / PHP 8.3 (Apache)Apache on $PORT
go.modGo (built into a small distroless image)The compiled binary

Override the build command, start command, port or root directory (for monorepos) in the app's Settings tab.

Database and Redis

Add PostgreSQL 16, MySQL 8.4 and/or Redis 7 when creating the app or later. They run next to your app on a private network that nothing else can reach, and their addresses arrive as DATABASE_URL and REDIS_URL. The Database tab lists tables with row counts and relationships, shows rows, and runs SQL (read-only unless you tick Allow changes). A backup is taken every day and the newest 7 are kept; download one from the tab or take one on demand. For a database shared by several apps or servers, use a managed database from Servers & databases.

Custom domains

Add your domain in the Domains tab and create a CNAME to <name>.run.hudhudexpress.com (or an A record to the address shown, for a bare domain). Press Check DNS; HTTPS is issued automatically once it resolves.

From the terminal and from agents

npm i -g hudhud-cloud
hudhud login
hudhud apps create shop --repo acme/shop --plan starter --db postgres --redis
hudhud deploy --app shop          # build the latest commit, stream the log, exit 1 on failure
hudhud logs shop -f               # live runtime logs
hudhud env set shop STRIPE_KEY=sk_live_… SESSION_TTL=3600
hudhud db query shop "SELECT count(*) FROM orders"
hudhud rollback shop              # previous version back live

AI agents connected over MCP get the same abilities: app_detect, app_create, app_deploy, app_build_log, app_logs, app_env_set, app_add_database, app_db_query, app_rollback and more. A typical loop: the agent pushes a fix, reads app_build_log, and checks app_logs until the error is gone. Moving from another host? See the migration guides.

Sites (static, deploy from GitHub)

Host static sites (plain HTML, React, Vue, Svelte, Astro, or Next.js with output: "export") at https://<name>.apps.hudhudexpress.com. Your site is built on GitHub's machines, then the files are uploaded to HudHud. Pushes to main go live, every pull request gets its own preview address, and earlier versions can be made live again with one click.

  1. Create a site in Console → Sites and press Connect GitHub.
  2. Create the deploy token there and add it to your repository as the secret HUDHUD_TOKEN.
  3. Add the workflow it shows as .github/workflows/hudhud.yml:
name: Deploy to HudHud
on:
  push:
    branches: [main]
  pull_request:
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm ci && npm run build
      - run: npx --yes --package=/sdk/hudhud-cloud.tgz hudhud deploy dist --site myshop
        env:
          HUDHUD_TOKEN: ${{ secrets.HUDHUD_TOKEN }}
Live addresshttps://myshop.apps.hudhudexpress.com
Branch previewhttps://myshop--feature-login.apps.hudhudexpress.com (latest deploy of that branch)
Exact deployhttps://myshop--1a2b3c4d.apps.hudhudexpress.com (first 8 characters of the deploy id)
Routing/about → /about/ → about/index.html; /page → page.html; your 404.html for missing pages; single-page apps can send unknown paths to index.html
Limits10 sites, 25 MB per file, 5,000 files and 200 MB per deploy; the newest 20 deploys are kept (plus whichever is live)

Custom domains

Open the site in the console, choose Custom domain and add e.g. www.myshop.et. Create the two DNS records shown: a TXT record _hudhud-challenge.www.myshop.et proving you own the domain, and a CNAME to myshop.apps.hudhudexpress.com (for a root domain such as myshop.et, an A record to the address shown). Press Check DNS: the site is live on the domain immediately, and HudHud issues a free HTTPS certificate within a few minutes and renews it automatically. On Cloudflare, keep the records "DNS only" until HTTPS is active.

Only changed files are uploaded, so most deploys take seconds. You can also deploy without GitHub with hudhud deploy ./dist --site myshop --prod, or by uploading a folder in the console. Sites that run server code (Node.js, PHP) are coming next.

SDKs and command line

Official libraries wrap the API with typed methods, retries for reads, and a webhook signature helper. Both read HUDHUD_TOKEN from the environment.

Node.js 18+ (no dependencies, TypeScript types included)

npm install /sdk/hudhud-cloud.tgz

const { HudHud } = require('hudhud-cloud');
const hh = new HudHud();                       // uses HUDHUD_TOKEN
const { id } = await hh.verify.send({ to: '251911234567', appName: 'My Bank' });
const { valid } = await hh.verify.check({ id, code });
await hh.sms.send({ to: '251911234567', text: 'Your order has shipped' });
await hh.storage.upload('invoices', '2026/oct.pdf', fs.readFileSync('oct.pdf'), 'application/pdf');
HudHud.verifyWebhook(secret, req.headers, rawBody);   // true / false

Python 3.8+ (standard library only)

pip install /sdk/hudhud-cloud-python.tar.gz

from hudhud_cloud import HudHud, verify_webhook
hh = HudHud()
v = hh.verify.send("251911234567", appName="My Bank")
hh.verify.check(code, id=v["id"])["valid"]

Command line: the Node package installs hudhud.

npm install -g /sdk/hudhud-cloud.tgz
hudhud login                         # paste an access token
hudhud sms send 251911234567 "Hello from HudHud"
hudhud verify send 251911234567 --app "My Bank"
hudhud dns records <zoneId>
hudhud storage put invoices ./oct.pdf 2026/oct.pdf
hudhud webhooks add https://api.example.et/hooks invoice.paid sms.failed
hudhud mcp cursor                    # print the AI-tool setup

Add --json to any command for machine-readable output. Exit codes: 0 success, 1 error or invalid code, 2 usage, 3 not signed in.

Usage, spend and alerts

The Usage & spend page shows SMS and Verify traffic, delivery rate, daily spend, top-ups, invoices due, sites storage and webhook health, plus how many days your wallet balance will last at the current rate. Download a CSV statement for reconciliation.

Alerts for low wallet balance and for daily or monthly spend are sent by email, SMS and the webhook events balance.low and spend.threshold, once each time a level is crossed. API (needs billing:read): GET /api/usage?days=30, GET /api/usage/statement.csv?from=YYYY-MM-DD&to=YYYY-MM-DD, GET /api/usage/alerts.

Webhooks

Add an endpoint in Console → Webhooks (or with POST /api/webhooks, or by asking your AI agent). HudHud then sends a signed POST with a JSON body whenever a chosen event happens.

{
  "id": "evt_4f1c…",
  "type": "invoice.paid",
  "createdAt": "2026-10-30T13:44:43.555Z",
  "data": { "invoiceNumber": "HH-2026-0142", "amount": 1500, "currency": "ETB", "provider": "chapa" }
}

Events

EventWhen
Loading…

Verify the signature

Signatures follow the Standard Webhooks spec, so their libraries for Node, Python, PHP, Go and others work as-is. Each request has webhook-id, webhook-timestamp and webhook-signature headers. The signature is an HMAC-SHA256 of id.timestamp.body, keyed with the base64 part of your whsec_… secret. Use the raw body exactly as received, and reject timestamps more than 5 minutes old.

// Node.js (Express)
app.post('/hudhud/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const id = req.get('webhook-id'), ts = req.get('webhook-timestamp'), body = req.body.toString();
  const key = Buffer.from(process.env.HUDHUD_WEBHOOK_SECRET.replace('whsec_', ''), 'base64');
  const expected = crypto.createHmac('sha256', key).update(id + '.' + ts + '.' + body).digest('base64');
  const ok = req.get('webhook-signature').split(' ').some(s => s === 'v1,' + expected);
  if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
  const event = JSON.parse(body);   // handle event.type; use event.id to ignore duplicates
  res.sendStatus(200);
});
# Python (Flask)
key = base64.b64decode(os.environ["HUDHUD_WEBHOOK_SECRET"].removeprefix("whsec_"))
signed = f"{request.headers['webhook-id']}.{request.headers['webhook-timestamp']}.{request.get_data(as_text=True)}"
expected = "v1," + base64.b64encode(hmac.new(key, signed.encode(), hashlib.sha256).digest()).decode()
if not any(hmac.compare_digest(s, expected) for s in request.headers["webhook-signature"].split()): abort(401)

Delivery and retries

Answer with any 2xx within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours (7 attempts in total). The same event keeps its webhook-id across retries, so use it to ignore duplicates. After 15 events in a row fail every attempt, the endpoint is turned off and the console shows why. Every delivery, with its HTTP status and response, appears in the console, where you can retry it.

Endpoints must be public https:// URLs. HudHud does not follow redirects, and it refuses addresses that resolve to private networks.

API reference

All endpoints accept and return JSON. Base URL:

EndpointPurposeNeeds
GET/api/appsYour appsapps:read
POST/api/apps/detectWhat a repository is and how it will runapps:read
POST/api/appsCreate an app and start its first deployapps:write
GET/api/apps/:appStatus, deployments, add-ons, domainsapps:read
POST/api/apps/:app/deployDeploy the latest (or a given) commitapps:write
GET/api/apps/:app/deployments/:idOne deployment with its build logapps:read
POST/api/apps/:app/rollbackPut an earlier deployment back liveapps:write
GET/api/apps/:app/logsRuntime logs; ?follow=1 streams NDJSONapps:read
PUT/api/apps/:app/envSet or remove environment variables (restarts)apps:write
POST/api/apps/:app/database/queryRun SQL; read-only unless allowWritesapps:write
GET/api/auditActivity log; ?source=mcp|api|consoleaccount:read
POST/api/sms/quoteCharacters, SMS parts and price—
POST/api/sms/sendSend one SMSsms:send
GET/api/catalog/plansAll plans and prices—
GET/api/domains/check?domain=Domain availability—
GET/api/cloudflare/zonesYour Cloudflare zonesdns:read
GET/api/cloudflare/zones/:zone/dnsDNS records; ?type=&name=dns:read
POST/api/cloudflare/zones/:zone/dnsCreate a recorddns:write
PATCH/api/cloudflare/zones/:zone/dns/:idChange a recorddns:write
DELETE/api/cloudflare/zones/:zone/dns/:idDelete a recorddns:write
POST/api/cloudflare/zones/:zone/purgePurge {"files":[…]} or everythingdns:write
GET/api/storage/bucketsList buckets and storage limitsstorage:read
POST/api/storage/bucketsCreate {"name","quotaGb","versioning"}storage:write
DELETE/api/storage/buckets/:bucketDelete an empty bucketstorage:write
PUT/api/storage/buckets/:bucket/versioningTurn versioning on or offstorage:write
GET/api/storage/buckets/:bucket/objectsList files; ?prefix=&cursor=&delimiter=/storage:read
GET/api/storage/buckets/:bucket/usageBytes used against quotastorage:read
POST/api/storage/buckets/:bucket/upload-urlSigned upload linkstorage:write
POST/api/storage/buckets/:bucket/download-urlSigned download linkstorage:read
DELETE/api/storage/buckets/:bucket/objects?key=Delete a filestorage:write
GET/api/status/summaryLive status by region and 30-day availability—

Errors and limits

Errors return a JSON body with an error message you can show to people, and sometimes extra fields such as requiredScope or remaining.

StatusMeaning
400Something in the request is invalid — the message says what.
401The token is missing, wrong, expired or revoked.
403The token lacks a permission, or a limit (trial allowance, quota) was reached.
404The bucket, record, invoice or route doesn't exist on your account.
409Conflict — for example a bucket that already exists, or Cloudflare not connected yet.
429Too many requests. Wait a minute and retry.
502 / 503An upstream service (SMS gateway, Cloudflare, storage) didn't respond, or isn't enabled yet.

Rate limits per token: 240 requests a minute on the developer endpoints and 120 MCP calls a minute. SMS sending also follows your account's SMS rate limit and daily quota.