DocsOverviewQuick StartFrameworksDeploymentsDomainsEnv VarsFeature FlagsAI GatewayAPI ReferenceWebhooks

Webhooks & Hooks

Webhooks & deploy hooks

Two complementary systems: Deploy Hooks let external services trigger your deployments. Outbound Webhooks let Deploxa notify your systems when events happen.

Deploy hooks (inbound)

A deploy hook is a unique URL that triggers a deployment when any HTTP request hits it. Use it to connect headless CMSs, CI pipelines, cron schedulers, or any other system that needs to trigger a build.

Create a deploy hook

Go to Project → Settings → Deploy Hooks → New Hook. Choose the branch and give the hook a descriptive name. Copy the generated URL — it cannot be viewed again after creation.

POSThttps://deploxa.app/api/v1/hooks/dh_a1b2c3d4e5f6…

Trigger a deploy

Send any HTTP request (GET or POST) to the hook URL. Deploxa ignores the request body — it queues a deployment for the configured branch immediately.

curl

# Trigger a production deployment curl -X POST https://deploxa.app/api/v1/hooks/dh_a1b2c3d4e5f6

You can also pass optional parameters to override the default branch or add a deploy message:

curl

curl -X POST https://deploxa.app/api/v1/hooks/dh_a1b2c3d4e5f6 \ -H "Content-Type: application/json" \ -d '{ "branch": "staging", "message": "Triggered by CMS publish" }'

Common use cases

Headless CMS

Contentful, Sanity, Strapi — rebuild on content publish.

Cron rebuild

Trigger nightly rebuilds for static sites with external data.

CI/CD pipeline

Deploy after tests pass in GitHub Actions, CircleCI, etc.

Slack command

Create a /deploy Slack slash command for your team.

Outbound webhooks

Configure Deploxa to POST to your endpoint whenever platform events occur. Useful for Slack notifications, PagerDuty alerts, custom dashboards, or audit pipelines.

Configure an outbound webhook

Go to Project → Settings → Outbound Webhooks → Add Webhook. Enter your endpoint URL, select which events to subscribe to, and save. Deploxa generates a signing secret you use to verify requests.

Available events

EventDescription
deployment.createdFires when a new deployment is queued.
deployment.buildingFires when the builder starts processing.
deployment.readyFires when a deployment goes live successfully.
deployment.errorFires when a deployment fails.
deployment.cancelledFires when a deployment is manually cancelled.
domain.addedFires when a custom domain is added to a project.
domain.verifiedFires when a domain passes DNS verification.
domain.removedFires when a domain is removed.

Webhook payload

All outbound webhooks deliver a JSON body with a consistent envelope:

JSON

{ "id": "evt_01j9ab12345", "event": "deployment.ready", "timestamp": "2026-05-27T14:32:49Z", "project": { "id": "proj_abc", "name": "my-app" }, "data": { "deployment": { "id": "dep_xyz", "status": "READY", "url": "https://my-app.deploxa.app", "commitSha": "abc1234", "branch": "main", "createdAt": "2026-05-27T14:32:01Z", "readyAt": "2026-05-27T14:32:49Z" } } }

Verifying webhook signatures

Every outbound webhook request includes a X-Deploxa-Signature header. Verify it to ensure the request came from Deploxa and hasn't been tampered with.

The signature is an HMAC-SHA256 of the raw request body, keyed with your webhook signing secret. Always verify on your server before processing the payload.

Node.js

import crypto from "crypto"; function verifyWebhook(rawBody: Buffer, signature: string, secret: string): boolean { const expected = crypto .createHmac("sha256", secret) .update(rawBody) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(expected, "hex"), Buffer.from(signature, "hex"), ); } // In your Express handler: app.post("/webhooks/deploxa", express.raw({ type: "application/json" }), (req, res) => { const sig = req.headers["x-deploxa-signature"] as string; if (!verifyWebhook(req.body, sig, process.env.DEPLOXA_WEBHOOK_SECRET!)) { return res.status(401).send("Invalid signature"); } const event = JSON.parse(req.body.toString()); // Handle event... res.status(200).send("ok"); });

Python

import hmac import hashlib def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) # In your FastAPI handler: @app.post("/webhooks/deploxa") async def handle_webhook(request: Request): raw_body = await request.body() sig = request.headers.get("x-deploxa-signature", "") if not verify_webhook(raw_body, sig, os.environ["DEPLOXA_WEBHOOK_SECRET"]): raise HTTPException(status_code=401, detail="Invalid signature") event = json.loads(raw_body) # Handle event...

Retries and delivery guarantees

Deploxa retries failed deliveries up to 5 times with exponential backoff.
A delivery is considered successful if your endpoint returns 2xx within 10 seconds.
Failed deliveries are visible in Project → Settings → Outbound Webhooks → Delivery Log.
You can manually replay any failed delivery from the delivery log.
AI GatewayREST API Reference