Hosting API Automation - Deploys, DNS and Webhooks for SA Teams

A hosting API lets you do from code what you'd otherwise click through in a dashboard: trigger deploys, read deployment status, manage configuration and react to events through webhooks. It's how agencies onboard clients in minutes, how teams post "deployed" messages into chat, and how you stop repeating the same ten clicks for every project. This guide covers what's worth automating, how API keys and webhooks fit together, and the patterns that keep automation safe.

What a hosting API is (and isn't)

A hosting REST API exposes your account's resources (apps, deployments, domains, databases and so on) as HTTP endpoints. You authenticate with an API key, send JSON and get JSON back.

It complements, rather than replaces, Git-based deploys. On NewHost, connecting a GitHub or GitLab repository means a push to your chosen branch deploys automatically through a webhook. For most teams that covers day-to-day releases. The API is for everything around the deploy: orchestration, reporting, integration with other systems and bulk operations.

What's worth automating

Start with notifications. They're low risk, immediately useful and teach you the webhook flow.

API keys - treat them like passwords

Your API key can change your hosting. Handle it accordingly:

1. One key per integration. Your CI system, your chat bot and your reporting script each get their own key, so you can revoke one without breaking the others.
2. Store keys in environment variables or a secrets manager, never in a repository. On NewHost, app environment variables are encrypted.
3. Rotate keys when someone leaves the team or a key may have been exposed.
4. Protect the account itself with two-factor sign-in, since anyone in the dashboard can create keys.

On NewHost the API lives at https://api.newhost.co.za/v1 and takes your secret key as a bearer token:

# List your apps
curl https://api.newhost.co.za/v1/apps \
  -H "Authorization: Bearer $NEWHOST_API_KEY"

# Trigger a deployment of one app
curl -X POST https://api.newhost.co.za/v1/apps/APP_ID/deployments \
  -H "Authorization: Bearer $NEWHOST_API_KEY"

The endpoints you will use most:

Keys have scopes (for example read-only, or allowed to deploy), so give each integration only what it needs. The full reference, with request bodies and a Postman collection, is at docs.newhost.co.za.

Webhooks - let the platform tell you

Polling ("is the deploy done yet?" every ten seconds) is wasteful and slow. Webhooks invert that: you register a URL, and the platform sends an HTTP POST when something happens, such as deployment.succeeded.

A minimal Express receiver that posts to a chat channel:

import express from "express";

const app = express();
app.use(express.json());

app.post("/hooks/hosting", async (req, res) => {
  // Acknowledge quickly; do slow work after responding.
  res.sendStatus(200);

  const event = req.body;
  if (event.type === "deployment.succeeded") {
    await fetch(process.env.CHAT_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: `Deployed: ${JSON.stringify(event.data)}` }),
    });
  }
});

app.listen(process.env.PORT || 3000);

Check the docs for the exact payload shape before reading specific fields. Before going live, add three things this sketch leaves out:

• Signature verification. Verify the request really came from your host and reject anything that fails. NewHost signs every webhook with your endpoint's secret in an X-NewHost-Signature header of the form t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">, and sends the event name in X-NewHost-Event and a unique X-NewHost-Delivery ID you can use to ignore duplicates. See webhooks explained for verification code.
• Idempotency. Webhooks can be delivered more than once. Store each event ID and skip ones you've already handled.
• Fast responses. Return 2xx quickly and push slow work to a queue or background job, or the sender may time out and retry.

Webhooks explained walks through HMAC verification, retries and idempotency in detail.

Deploy on demand

Sometimes you want a deploy without a new commit, for example after a content change in a headless CMS, or to rebuild a static site at a set time. There are a few ways to do this:

• Push-based: have the CMS commit to the repository, and let the Git webhook deploy it. Simple, fully traceable in Git history.
• API-based: call a deploy endpoint from the CMS webhook or a script, where the API offers one.
• Avoid the rebuild: for Next.js, on-demand revalidation can refresh specific pages without a full deploy. That's often the better answer for content changes.

For scheduled work that isn't a deploy (sending reports, clearing old records, syncing data), use scheduled tasks instead. NewHost runs cron-style tasks as often as every five minutes; see cron jobs for Node.js.

Safe automation patterns

Automation multiplies mistakes as easily as it multiplies productivity. A few habits help:

• Dry-run mode. Scripts that change things should print what they would do before doing it.
• Least privilege. Where roles exist, give automation only the access it needs, and keep billing access separate.
• Log every change your scripts make, with the key that made it.
• Idempotent scripts. Running a setup script twice should not create two of everything. Check whether a resource exists first.
• Don't automate destructive actions casually. Deleting apps, databases or DNS zones should need a human, or at least an explicit confirmation flag.
• Test on a throwaway project before pointing a script at client sites.

A simple first project

A good first automation for a small team:

1. Create an API key named "chat-notifications".
2. Deploy the webhook receiver above as a small app.
3. Register its URL for deployment events (the docs explain how), and store any signing secret as an environment variable.
4. Add signature verification and event-ID de-duplication.
5. Push a commit and watch the message arrive.

Once that works, extend it: trigger a smoke test on each deploy and post the result alongside the notification. Pair it with the release flow in simple CI/CD for small teams.

Frequently asked questions

What is a hosting API used for?

It lets scripts and other systems manage your hosting without the dashboard: reading and triggering deployments, reacting to events via webhooks, and setting up projects consistently. Agencies and teams use it to remove repetitive manual steps.

Do I need the API if I already deploy from Git?

Not for everyday releases, since a push to your branch already deploys. The API and webhooks are for what happens around deploys, such as notifications, checks, reporting and integration with tools like a CMS.

Are webhooks secure?

They can be, if you verify the signature on each request, use HTTPS, and ignore duplicate or unexpected events. Treat an unverified webhook as untrusted input.

Where do I find the NewHost API endpoints?

The REST API, authentication and webhook events are documented at docs.newhost.co.za. Create API keys in the dashboard at app.newhost.co.za.

See what you can automate on the automation page, then start with the reference at docs.newhost.co.za.