Notifications¶

Stay informed about your deployments through Versioner's notification channels. All channels are configured under Settings → Notifications.

Overview¶

Channel	Trigger	Best for
Slack	Deployment and build events	Team alerting in Slack
Email	Deployment and build events	Teams without Slack, or distribution lists
Webhook	Deployment, build, and governance events	DORA dashboards, incident tools, agentic pipelines, custom automation
DR Approval Emails	Deployment Request approval flow	Action-oriented approval notifications

Slack and Email fire on deployment and build events. Webhook additionally covers DR lifecycle and version approval events — governance-plane events suited for downstream automation rather than person-facing alerts. DR Approval Emails are a separate system tied to the Deployment Request governance flow.

Slack¶

Event-based notifications to Slack channels. Multiple channels can be configured, each with its own event subscriptions.

Setup¶

Go to api.slack.com/apps and create or select an app
Enable Incoming Webhooks and add a webhook to your desired channel
Copy the webhook URL
In Versioner, go to Settings → Notifications → Slack and add a new channel
Paste the webhook URL, choose which events to subscribe to, and save

Use the Test button to verify delivery before going live.

Event types¶

Event	Description
`deployment.pending`	Deployment queued
`deployment.started`	Deployment in progress
`deployment.completed`	Deployment succeeded
`deployment.failed`	Deployment failed
`deployment.aborted`	Deployment cancelled
`build.pending`	Build queued
`build.started`	Build in progress
`build.completed`	Build succeeded
`build.failed`	Build failed
`build.aborted`	Build cancelled

Multiple channels¶

Send different events to different channels — add one channel config per destination:

#deployments → subscribe to deployment.completed
#alerts → subscribe to deployment.failed

Email¶

Org-level email notifications for deployment and build events. Configured the same way as Slack — one recipient address (or distribution list) per configuration, under Settings → Notifications → Email.

This is intentionally org-level, not user-specific. User-specific notification subscriptions are a separate future effort.

Setup¶

In Versioner, go to Settings → Notifications → Email and add a new channel
Enter the recipient email address or distribution list
Choose which events to subscribe to and save

Email content includes: product name, environment, status, deployer, timestamp, and a link to the deployment in Versioner.

Webhook¶

Outbound webhook that fires a JSON POST to your endpoint on deployment, build, and governance events. Use this to feed DORA dashboards, incident tools, audit systems, or custom workflows.

Setup¶

Go to Settings → Notifications → Webhook and add a new channel
Enter the destination URL
Optionally enter an HMAC secret for payload verification
Choose which events to subscribe to and save

Request format¶

Every request includes:

Content-Type: application/json
X-Versioner-Event: <event_type>
X-Versioner-Signature: sha256=<hex>   # only if HMAC secret configured

CI/CD events¶

Deployment and build events — use these for DORA metrics, incident tooling, and deployment tracking.

Event types¶

Event	Description
`deployment.pending`	Deployment queued
`deployment.started`	Deployment in progress
`deployment.completed`	Deployment succeeded
`deployment.failed`	Deployment failed
`deployment.aborted`	Deployment cancelled
`build.pending`	Build queued
`build.started`	Build in progress
`build.completed`	Build succeeded
`build.failed`	Build failed
`build.aborted`	Build cancelled

Payload reference¶

Field	Type	Nullable	Description
`id`	string	No	Versioner deployment UUID
`deployed_at`	string	No	ISO 8601 timestamp (UTC)
`event_type`	string	No	See event types table
`environment`	string	No	Target environment name
`is_successful`	bool	Yes	See `is_successful` table below
`deployer`	string	Yes	Name of deployer
`product_name`	string	Yes	Versioner product name
`version`	string	Yes	Version string being deployed
`repo_name`	string	Yes	`scm_repository` if provided
`commit_sha`	string	Yes	`scm_sha` if provided
`preflight_status`	string	Yes	`passed`, `failed`, `skipped`, or null
`source_url`	string	Yes	Link to deployment in Versioner console

`is_successful` by event type¶

is_successful is only set for terminal deployment states. Non-terminal events and all build events receive null.

`event_type`	`is_successful`
`deployment.completed`	`true`
`deployment.failed`	`false`
`deployment.preflight_failed`	`false`
`deployment.pending`	`null`
`deployment.started`	`null`
`deployment.aborted`	`null`
`build.pending`	`null`
`build.started`	`null`
`build.completed`	`null`
`build.failed`	`null`
`build.aborted`	`null`

Filtering for DORA / Jellyfish success and failure

If you're filtering webhook events to capture only successful and failed deployments (e.g. for DORA metrics or Jellyfish), filter on event_type — not is_successful alone.

is_successful == false matches both deployment.failed and deployment.preflight_failed. If you want to exclude preflight failures from your DORA data (since no deployment actually started), filter on event_type == "deployment.failed" explicitly.

Subscribe only to deployment.completed and deployment.failed events for the cleanest DORA feed.

Example payload¶

{
  "id": "ac37da84-0891-48ae-9011-6500665804ee",
  "deployed_at": "2026-05-24T14:06:05.890103+00:00",
  "event_type": "deployment.completed",
  "environment": "production",
  "is_successful": true,
  "deployer": "Phil Austin",
  "product_name": "my-ui",
  "version": "1.2.6",
  "repo_name": "versioner-io/versioner-ui",
  "commit_sha": "a3f9c2d1e4b5...",
  "preflight_status": "passed",
  "source_url": "https://app.versioner.io/manage/deployments?view=ac37da84-0891-48ae-9011-6500665804ee"
}

DR lifecycle and approvals¶

DR lifecycle and version approval events are delivered via outbound webhook only — not Slack or email. Use these to trigger pipelines, update incident tools, or drive agentic workflows that react to the state of a deployment or approval.

Event types¶

Event	Fires when
`dr.created`	A Deployment Request is created (by a human or agent)
`dr.activated`	A DR moves to In Progress — approval flow begins
`dr.deactivated`	A DR is reverted to draft
`dr.approved`	An approval slot is filled — fires once per slot, not once when all approved
`dr.rejected`	An approval slot is explicitly denied
`dr.completed`	A DR is marked complete
`dr.cancelled`	A DR is cancelled
`version.approved`	A quality sign-off is recorded on a version, independent of any DR

DR payload reference¶

Field	Type	Nullable	Description
`event_type`	string	No	One of the `dr.*` event types above
`occurred_at`	string	No	ISO 8601 timestamp (UTC)
`dr_id`	string	No	Deployment Request UUID
`dr_name`	string	No	DR name (e.g. `"Q4 2025 Release"`)
`dr_url`	string	No	Link to the DR in the Versioner console
`status`	string	No	DR status at time of event
`environment_names`	array	No	Target environment names
`actor`	string	Yes	Name of the user who took the action
`approval_type`	string	Yes	Approval type (`qa`, `security`, etc.) — present on `dr.approved` / `dr.rejected`
`approver_role`	string	Yes	Role of the approver — present on `dr.approved` / `dr.rejected`
`slot_status`	string	Yes	`"approved"` or `"rejected"` — present on `dr.approved` / `dr.rejected`
`comments`	string	Yes	Reviewer comments — present on `dr.approved` / `dr.rejected` if provided

`version.approved` payload reference¶

Field	Type	Nullable	Description
`event_type`	string	No	`"version.approved"`
`occurred_at`	string	No	ISO 8601 timestamp (UTC)
`version_id`	string	No	Version UUID
`product_name`	string	No	Product name
`version`	string	No	Version string (e.g. `"1.2.6"`)
`approval_type`	string	No	Approval type (`qa`, `security`, etc.)
`approver_role`	string	No	Role of the approver
`environment_name`	string	Yes	Environment the sign-off was scoped to, if any
`comments`	string	Yes	Approver comments
`actor`	string	Yes	Name of the approver

Example payloads¶

dr.activated:

{
  "event_type": "dr.activated",
  "occurred_at": "2026-05-25T09:14:33.201045+00:00",
  "dr_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "dr_name": "Q4 2025 Release",
  "dr_url": "https://app.versioner.io/deployment-requests/7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "in_progress",
  "environment_names": ["production"],
  "actor": "Phil Austin"
}

dr.approved (approval slot filled):

{
  "event_type": "dr.approved",
  "occurred_at": "2026-05-25T09:22:11.004321+00:00",
  "dr_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "dr_name": "Q4 2025 Release",
  "dr_url": "https://app.versioner.io/deployment-requests/7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "in_progress",
  "environment_names": ["production"],
  "actor": "Jane Smith",
  "approval_type": "qa",
  "approver_role": "qa_engineer",
  "slot_status": "approved",
  "comments": "All regression tests passed."
}

version.approved:

{
  "event_type": "version.approved",
  "occurred_at": "2026-05-25T08:55:44.112233+00:00",
  "version_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "product_name": "api-service",
  "version": "2.4.1",
  "approval_type": "qa",
  "approver_role": "qa_engineer",
  "environment_name": "staging",
  "comments": "Load tests passed, ready for production.",
  "actor": "Jane Smith"
}

Retry behavior¶

On 5xx or network errors: 3 attempts with exponential backoff (1 s, 2 s). 4xx responses are treated as terminal — no retry.

HMAC signature verification¶

When a secret is configured, Versioner signs the raw compact-JSON body and adds X-Versioner-Signature: sha256=<hex>. Verify on receipt before parsing the body.

PythonJavaScript

import hmac, hashlib

def verify_signature(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

const crypto = require("crypto");

function verifySignature(secret, rawBody, header) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Warning

Compute the HMAC over the raw request body bytes before any JSON parsing. The body is compact JSON (no spaces).

DR Approval Emails¶

DR approval emails are automatic — there's nothing to configure here. When a Deployment Request moves to In Progress, Versioner emails users whose role matches an approval slot. See Deployment Requests for how the approval flow works.

Event Types — full event type reference
Deployment Requests — how DRs and approval slots work
Deployments — what triggers deployment events

Notifications¶

Overview¶

Slack¶

Setup¶

Event types¶

Multiple channels¶

Email¶

Setup¶

Webhook¶

Setup¶

Request format¶

CI/CD events¶

Event types¶

Payload reference¶

is_successful by event type¶

Example payload¶

DR lifecycle and approvals¶

Event types¶

DR payload reference¶

version.approved payload reference¶

Example payloads¶

Retry behavior¶

HMAC signature verification¶

DR Approval Emails¶

Related¶

`is_successful` by event type¶

`version.approved` payload reference¶