Webhooks
Webhooks tell your systems when something happens in your NewHost account, such as a deployment finishing, a payment clearing or a domain being registered. NewHost sends an HTTPS POST with a JSON body to each endpoint subscribed to that event.
Adding an endpoint
- In the dashboard: Developers → Webhooks → Add endpoint, or via the API with
POST /v1/webhooks. - The URL must be public and use
https://. - Pick the events you want, or all of them. You get a signing secret (
whsec_…) to verify requests. - Use Send test event to deliver a
pingevent and see your endpoint's response.
Event types
| Event | When |
|---|---|
app.created | An application was created |
app.deleted | An application was deleted |
deployment.started | A deployment began running |
deployment.succeeded | A deployment finished successfully |
deployment.failed | A deployment failed |
backup.succeeded | An app backup finished |
backup.failed | An app backup failed |
preview.removed | A branch preview was removed (branch deleted, idle or by hand) |
domain.registered | A domain was registered |
database.created | A database was provisioned |
payment.succeeded | A card or instant-EFT payment was accepted |
payment.failed | A payment was declined |
subscription.activated | A plan subscription became active or renewed |
subscription.cancelled | A subscription was cancelled |
ping | Test event sent from the dashboard. |
deployment.failed and backup.failed carry error: a short message for people about what failed. For a failed Git step it includes Git's own message, e.g. a branch that doesn't exist. Show it, but don't parse it.
Request format
Headers
POST /hooks/newhost HTTP/1.1
Content-Type: application/json
User-Agent: NewHost-Webhooks/1.0
X-NewHost-Event: deployment.succeeded
X-NewHost-Delivery: clx8dlv0001
X-NewHost-Signature: t=1790000000,v1=5d41402abc4b2a76b9719d911017c592...Body
{
"id": "evt_3f9d2c1ab4e5f6a7b8c9d0e1",
"type": "deployment.succeeded",
"created": "2026-09-24T10:17:42.000Z",
"data": {
"deploymentId": "clx8dep0001",
"applicationId": "clx8app0001",
"commitSha": "9f2c1ab…",
"url": "https://shop.example.com",
"skippedSteps": []
}
}Every deployment.* event carries deploymentId, applicationId and commitSha (the full 40-character commit; null on deployment.started until the branch's latest commit is fetched). A branch preview adds previewId and branch. deployment.started has trigger, deployment.succeeded has the site's url, and deployment.failed has error. appId is the same as applicationId and stays for older integrations.
deployment.succeeded also has skippedSteps: the steps the deployment went on without, each as { "step": "Check app files are private", "detail": "..." }, the same as the warnings above the deployment's log in the dashboard. It is empty when every step ran. A deployment that went on without a step is live, but may need you: for example, if Check app files are private is listed, the app's files could be downloaded from the site. Show detail to people; match on step.
id is the same for every endpoint that receives the event and across retries, so use it to ignore duplicates. X-NewHost-Delivery identifies one delivery attempt.
Verifying signatures
X-NewHost-Signature holds a Unix timestamp t and v1, the hex HMAC-SHA256 of t + "." + raw body keyed with your endpoint's secret. Recompute it over the raw request body (before JSON parsing), compare in constant time, and reject timestamps older than five minutes to stop replays.
Node.js (Express)
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/hooks/newhost", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("X-NewHost-Signature") ?? "";
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", process.env.NEWHOST_WEBHOOK_SECRET)
.update(`${t}.${req.body}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
const valid = v1 && expected.length === v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
if (!fresh || !valid) return res.status(400).send("bad signature");
const event = JSON.parse(req.body);
// ...handle event.type, using event.id to skip duplicates
res.sendStatus(200);
});PHP
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_NEWHOST_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . $body, getenv('NEWHOST_WEBHOOK_SECRET'));
if (abs(time() - (int) $sig['t']) > 300 || !hash_equals($expected, $sig['v1'] ?? '')) {
http_response_code(400);
exit('bad signature');
}
$event = json_decode($body, true);
http_response_code(200);Python (Flask)
import hmac, hashlib, os, time
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/hooks/newhost")
def newhost():
parts = dict(p.split("=", 1) for p in request.headers.get("X-NewHost-Signature", "").split(","))
body = request.get_data()
expected = hmac.new(os.environ["NEWHOST_WEBHOOK_SECRET"].encode(), f"{parts.get('t')}.".encode() + body, hashlib.sha256).hexdigest()
if abs(time.time() - int(parts.get("t", 0))) > 300 or not hmac.compare_digest(expected, parts.get("v1", "")):
abort(400)
event = request.get_json()
return "", 200Responding and retries
- Return any
2xxwithin 10 seconds. Do slow work after responding, e.g. on a queue. - Anything else (or a timeout) is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours: six attempts over about 15 hours.
- Redirects are not followed; point the endpoint at the final URL.
- After 50 failed deliveries in a row the endpoint is disabled and the account owner is e-mailed. Fix it, then enable it again in the dashboard; events from while it was disabled are not sent.
- The endpoint page shows recent deliveries with the response we received, and lets you resend any of them.
id.