Docs
Chat, webhooks and API tokens
Send release events to Slack, Google Chat, email and your own endpoints, verify webhook signatures, and call DeployNX from CI with API tokens.
DeployNX tells your tools what happens in three ways: messages to Slack, Google Chat and email, approval buttons in Slack and Google Chat, and signed outgoing webhooks to your own HTTPS endpoints. In the other direction, your CI jobs and services call the DeployNX API with an API token. All of it lives in Settings: Integrations › Chat & email for channels and webhooks, General for API tokens. Everyone in the organization can see channels and webhooks, and owners and admins change them; any member can create an API token.
Chat and email channels
A channel is a Slack incoming webhook, a Google Chat webhook, an email list (up to 20 addresses), or a channel of the DeployNX Slack or Google Chat app. Add one under Channels with Add channel. Webhook URLs and addresses are stored encrypted.
These are the events a channel can receive:
| Event | Sent when |
|---|---|
| Production promotion requested | A release asks to go to a production-tier environment. The approvers also get an email. |
| Deploy or promotion approval requested | Any other deploy or promotion asks for approval. |
| Approval still waiting | A request is still pending after the reminder time on Settings › General (an hour unless you change it). |
| Deploy failed or unhealthy | A release failed, or its health check did. |
| Deploy healthy | A release passed its health check. |
| Rolled back | A release was rolled back, with Roll back or automatically after a failed health check. |
| Test run failed / Test run passed | A test run finished. |
| Freeze / break-glass | A freeze window or a break-glass session started or ended. |
| Access requested (chat only) | Someone asked for access to an environment. |
A new channel starts with every event except the two test run events and Deploy healthy. Turn events on and off per channel in the Events grid.
Routing. Open a channel to narrow it with Route by: Repositories takes comma-separated patterns on the repository name or owner/repo (payments-*, acme/api), and the environment boxes pick environments. All production covers every production-tier environment, including ones you add later. Leave both empty and the channel gets the event from every repository and environment.
Test send. Test send on a channel posts a sample message and shows the result in the row: sent, or the error the service answered. You can send five a minute per channel and fifty a day for the organization.
Delivery log. Every send is logged with its outcome. A failing channel shows its last error in the list. The log is kept for 30 days unless you shorten it on Settings › General.
Each person also picks which emails they get under Profile.
Approve from Slack or Google Chat
Install the apps from the Chat apps section. Connect Slack workspace installs the DeployNX Slack app and picks the channel it posts to. For Google Chat, add the DeployNX app to a space, then open the confirmation link it posts there (owners and admins).
Approval requests in an app’s channel carry Approve and Reject buttons. A click counts as yours only from a chat account linked to you, so link yours under Your identity. If it isn’t linked yet, the click answers with a one-time link, valid for 10 minutes, to confirm the account in DeployNX, and you decide there. The buttons run the same checks as the app: the request must still be pending, your role and approver team must allow it, the self-approval setting applies, and rejecting asks for a reason. See Approvals and policies for who can decide what.
Outgoing webhooks
DeployNX posts signed JSON to your own HTTPS endpoints when releases, approvals, test runs and freezes change. In the app they’re under Settings › Integrations › Chat & email › Outbound webhooks.
Add endpoint asks for the URL, an optional description and the events. The URL must be HTTPS on a public address; DeployNX checks the address on every attempt and doesn’t follow redirects. The endpoint’s signing secret is shown once, when you add it: copy it then. The Active switch pauses an endpoint without removing it.
| Event | Sent when |
|---|---|
release.started |
A release starts deploying. |
release.succeeded |
A release is healthy. |
release.failed |
A release failed, or failed its health check. |
release.rolled_back |
A release was rolled back, with Roll back or automatically after a failed health check. |
approval.requested |
A deploy or promotion asks for approval. |
approval.decided |
A request left the queue: approved, rejected, skipped, expired or replaced by a newer one. |
run.completed |
A test run finished. |
freeze.started |
A freeze window started. |
freeze.ended |
A freeze window ended. |
ping |
You chose Send test event. |
What a delivery looks like
Each delivery is a POST with a JSON body and these headers:
| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
DeployNX-Webhooks/1.0 |
X-DeployNX-Event |
The event, such as release.failed |
X-DeployNX-Delivery |
The delivery’s id, the same on each of its retries |
X-DeployNX-Signature |
sha256= and the hex HMAC-SHA256 of the raw body, keyed with the endpoint’s secret |
The body is always the same envelope. id names the event and never changes for it, created_at is when DeployNX created it (UTC), and data depends on the event:
{
"id": "6f1c2a4e-1d1b-4f0e-9a51-2b8f0f5c9d10",
"event": "release.failed",
"created_at": "2026-10-13T18:04:11.532118+00:00",
"organization_id": "8a3e5f0c-5d0e-4b7a-9a52-1f0c3e7d2b44",
"data": {
"deployment_id": "0b6c1d52-7a8e-4a0b-8f6e-3c9d2e1f4a57",
"repository": "acme/api",
"environment": "PRODUCTION",
"status": "unhealthy",
"release_tag": "main_3f9c2a1b7d4e",
"duration_seconds": null,
"error": "Health check failed after 5 attempts. Last error: HTTP 503",
"triggered_by": "ann@acme.example",
"url": "https://deploynx.bizstats.ai/app/releases/0b6c1d52-7a8e-4a0b-8f6e-3c9d2e1f4a57"
}
}
The body arrives as compact JSON; it’s shown spaced out here. Each event’s data:
release.started, when a release starts deploying (status is deploying):
{
"deployment_id": "0b6c1d52-7a8e-4a0b-8f6e-3c9d2e1f4a57",
"repository": "acme/api",
"environment": "PRODUCTION",
"status": "deploying",
"release_tag": "main_3f9c2a1b7d4e",
"triggered_by": "ann@acme.example",
"url": "https://deploynx.bizstats.ai/app/releases/0b6c1d52-7a8e-4a0b-8f6e-3c9d2e1f4a57"
}
release.succeeded, release.failed and release.rolled_back carry the fields in the envelope example above. environment is the environment’s name, with a production-tier one in capitals, and error, set on release.failed only, says what went wrong. release_tag, duration_seconds and triggered_by can be null.
- release.succeeded:
statusishealthy. A release is healthy once its health check passes, or once its pipeline does when it has no health check URL. Re-run health check on a release sendsrelease.succeededorrelease.failedwhen it changes the release’s status. - release.failed:
statusisunhealthywhen the release failed its health check, andfailedwhen its pipeline failed, timed out or couldn’t start, or when an automatic rollback couldn’t bring the earlier release back. When an unhealthy release rolls back automatically (see Releases and rollback),unhealthycomes first, thenrelease.rolled_backonce the earlier release runs again, orfailedwhen there’s none to go back to or the rollback fails. - release.rolled_back:
statusisrolled_back.deployment_idis the release that was replaced andrelease_tagthe earlier tag that runs again.triggered_byis who chose Roll back, or for an automatic rollback, who started the release that failed. A Roll back is itself a new release, with its ownrelease.startedand thenrelease.succeededorrelease.failed.
approval.requested, when a deploy or promotion asks for approval (promotion is true for a promotion to a production-tier environment):
{
"approval_id": "5d2f8b10-3c4a-4e6b-9f1d-7a8c0e2b4d61",
"repository": "acme/api",
"title": "Production promotion",
"promotion": true,
"requested_by": "ann@acme.example",
"url": "https://deploynx.bizstats.ai/app/approvals/5d2f8b10-3c4a-4e6b-9f1d-7a8c0e2b4d61"
}
approval.decided, when a request leaves the queue. status is approved, rejected, skipped, expired or superseded, and action is what settled it: approve, reject or skip when a person decided, expired or superseded when DeployNX did. decided_by is null when nobody decided it. A request that needs more than one approver sends nothing while it waits for the others, and sends this once it’s approved or rejected.
{
"approval_id": "5d2f8b10-3c4a-4e6b-9f1d-7a8c0e2b4d61",
"status": "approved",
"action": "approve",
"repository": "acme/api",
"environment": "Production",
"requested_by": "ann@acme.example",
"decided_by": {
"user_id": "c41e7f0a-2b6d-4c8e-9a3f-5d1b7e9c0a24",
"email": "omar@acme.example",
"name": "Omar Haddad"
},
"comment": null,
"deployment_id": "9e7a3c21-4f5b-4d8a-b6c0-1e2f3a4b5c6d",
"manual_run_id": null,
"url": "https://deploynx.bizstats.ai/app/approvals/5d2f8b10-3c4a-4e6b-9f1d-7a8c0e2b4d61"
}
run.completed, when a test run finishes. status is passed, failed, error or cancelled; total, passed and failed count the pipeline’s steps.
{
"run_id": "2c9e4a17-8b3d-4f6a-a5e1-0d7c9b2f3e48",
"repository": "acme/api",
"branch": "main",
"status": "failed",
"total": 6,
"passed": 5,
"failed": 1,
"duration_seconds": 312.4,
"triggered_by": "ann@acme.example",
"url": "https://deploynx.bizstats.ai/app/runs/2c9e4a17-8b3d-4f6a-a5e1-0d7c9b2f3e48"
}
freeze.started and freeze.ended. In freeze.started, until is when the freeze thaws; it’s sent again, with the new time, when someone changes the end of a freeze in effect. In freeze.ended, until is when the freeze ended. environments and repos are its scope (no repos means every repository). by is the display name of the person who started, changed or ended it (for a scheduled start, whoever created the freeze), and null when a freeze ends on schedule:
{
"freeze_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "Black Friday",
"reason": "Peak traffic",
"environments": ["All production"],
"repos": ["acme/*"],
"until": "2026-11-30T08:00:00+00:00",
"by": "Omar Haddad",
"url": "https://deploynx.bizstats.ai/app/policies?tab=freezes"
}
ping, the test event:
{
"message": "Test event from DeployNX webhook settings",
"sent_by": "omar@acme.example",
"url": "https://deploynx.bizstats.ai/app"
}
Verify the signature
Check X-DeployNX-Signature before you trust or even parse the body. Compute the HMAC-SHA256 of the raw request bytes with the endpoint’s secret, hex-encode it, put sha256= in front, and compare the result with the header in constant time. Sign the bytes you received, never JSON you parsed and wrote back out: re-serialized JSON rarely matches byte for byte.
Python:
import hashlib, hmac
def signed(secret: str, body: bytes, header: str | None) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return header is not None and hmac.compare_digest(expected.encode(), header.encode())
Node.js:
import { createHmac, timingSafeEqual } from 'node:crypto';
function signed(secret, body, header) {
const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(body).digest('hex'));
const given = Buffer.from(header ?? '');
return given.length === expected.length && timingSafeEqual(given, expected);
}
Answer 401 to anything unsigned or signed with another secret.
Answer fast, handle each event once
- Timing and retries. Each attempt waits up to 10 seconds for an answer. A timeout, a network error,
429or any5xxis tried again after 5 seconds and then after 30 seconds, three attempts in all. Any other answer settles the delivery:2xxcounts as delivered, anything else (redirects included) as failed. - Answer first. Reply
2xxas soon as the signature checks out, and do the work afterwards, on a queue or a background worker. A slow handler turns into timeouts and retries. - Idempotency. Retries repeat
X-DeployNX-Delivery, and both retries and redeliveries repeat the event’sid. Keep the ids you’ve handled and answer200to one you’ve seen, without doing the work again. Count an id as handled only once its work succeeded: if the work fails after you answered, forget the id, so a Redeliver gets it done. - Order. Deliveries can arrive out of order. Use
created_atand thestatusindata, not arrival order, to decide what’s current. - Replays. The signature covers the body,
created_atincluded, so a receiver can refuse events older than it cares about and only needs to remember ids for that long. A redelivery keeps the originalcreated_at, so allow for that if you redeliver older events.
Test, redeliver and rotate
- Send test event posts a
pingonce, while you wait, and shows the status code or the error in the row. - Open an endpoint and choose Deliveries to see each delivery’s status code or error, attempts, time taken and payload. Each endpoint keeps its newest 200. Redeliver sends a logged payload once more as a new delivery, with the same event
id. Test events and redeliveries count against the same limits as chat test sends: five a minute per endpoint, fifty a day for the organization. - Rotate secret issues a new secret, shown once, and the old one stops signing at once. Update your receiver, then redeliver anything that failed in between.
Calling DeployNX: API tokens
DeployNX doesn’t take incoming webhooks from CI or git hosts. The only things that call into DeployNX are the Slack and Google Chat apps, when someone clicks Approve or Reject, and the DeployNX GitHub App, which reports installation changes and finished workflow runs so green stage builds are found at once. When a CI job or one of your services needs to tell DeployNX something, it calls the API with an API token.
Create a token under Settings › General › API tokens: give it a name, pick its scopes and when it expires (in 7, 30 or 90 days, or a year). The token starts with dnx_ and is shown once; DeployNX keeps only a hash. Store it in your CI’s secret store and send it as Authorization: Bearer dnx_…. Any member can create tokens. Owners and admins see and revoke every token in the organization; members see and revoke their own.
A token acts as the person who created it, with the role they hold at the moment it’s used, and it stops working when they leave the organization. It never decides an approval, and it can only make the calls its scopes allow:
| Scope | Allows |
|---|---|
read |
Any GET request |
request_promotion |
POST /api/v1/deployments/{id}/promote |
run_tests |
POST /api/v1/repositories/{id}/test |
upload_results |
POST /api/v1/test-results |
The examples use DEPLOYNX=https://deploynx.bizstats.ai and the token in DEPLOYNX_TOKEN.
Request a promotion of a healthy release to the next environment on its route. The release id is the last part of its page’s URL, and data.deployment_id in a release.succeeded webhook. The answer is the new approval request (201); an approver still decides it.
curl -sS --fail-with-body -X POST "$DEPLOYNX/api/v1/deployments/$RELEASE_ID/promote" \
-H "Authorization: Bearer $DEPLOYNX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason": "Nightly checks passed"}'
It answers 409 with the reason when the release isn’t healthy, isn’t the newest healthy one, is already in the next environment, or already waits for approval there.
Start a test run on a branch. Find the repository’s id with a read token (each item in repositories has id and repo_full_name):
curl -sS --fail-with-body "$DEPLOYNX/api/v1/repositories?search=api" \
-H "Authorization: Bearer $DEPLOYNX_TOKEN"
curl -sS --fail-with-body -X POST "$DEPLOYNX/api/v1/repositories/$REPO_ID/test" \
-H "Authorization: Bearer $DEPLOYNX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"branch": "main", "commit_sha": "'"$GIT_COMMIT"'"}'
The run starts the repository’s pipeline as the token’s creator, on their own linked account at the git host. If they haven’t linked one (Profile › Connected accounts), the answer is 409 with "code": "identity_required".
Upload JUnit results for a run, named by repository and commit (or by run_kind=test and run_id). Send the XML as the body, or as a multipart file with -F file=@junit.xml; up to 10 MB and 20,000 test cases.
curl -sS --fail-with-body -X POST "$DEPLOYNX/api/v1/test-results?repository=acme/api&commit=$GIT_COMMIT" \
-H "Authorization: Bearer $DEPLOYNX_TOKEN" \
-H "Content-Type: application/xml" \
--data-binary @build/test-results/junit.xml
The answer counts what was recorded: recorded, passed, failed, skipped, and duplicates the run already had.
When a call is refused
| Status | Means |
|---|---|
401 |
The token is unknown, revoked or expired, or the person who created it is no longer in the organization. The message says which; create a new token. |
403 |
The token’s scopes don’t cover this call (“This token can’t do that (scopes: read)”), or its creator’s current role can’t do it. |
409 |
The request conflicts with the release’s state, or the creator needs to link their git account (identity_required). |
429 |
Your organization’s API rate limit. Wait the number of seconds in Retry-After. |
503 |
DeployNX couldn’t check the token with BizStats Hub just then. Try again. |
Every write a token makes is in the audit log under its creator’s name, with the token’s name beside it.