esc

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: status is healthy. 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 sends release.succeeded or release.failed when it changes the release’s status.
  • release.failed: status is unhealthy when the release failed its health check, and failed when 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), unhealthy comes first, then release.rolled_back once the earlier release runs again, or failed when there’s none to go back to or the rollback fails.
  • release.rolled_back: status is rolled_back. deployment_id is the release that was replaced and release_tag the earlier tag that runs again. triggered_by is 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 own release.started and then release.succeeded or release.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, 429 or any 5xx is tried again after 5 seconds and then after 30 seconds, three attempts in all. Any other answer settles the delivery: 2xx counts as delivered, anything else (redirects included) as failed.
  • Answer first. Reply 2xx as 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’s id. Keep the ids you’ve handled and answer 200 to 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_at and the status in data, not arrival order, to decide what’s current.
  • Replays. The signature covers the body, created_at included, so a receiver can refuse events older than it cares about and only needs to remember ids for that long. A redelivery keeps the original created_at, so allow for that if you redeliver older events.

Test, redeliver and rotate

  • Send test event posts a ping once, 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.