Create an Alert Channel : MinionWare

Creates a channel an alert rule can notify -- a webhook (Slack, Teams, or a generic URL) or an email (via SQL Server Database Mail or your own SMTP relay). One request shape covers every kind; send only the fields your kind uses and leave the rest null. There's no update endpoint -- to change a channel, delete and recreate it (after reassigning any rules still pointed at it).

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

Authenticate to the API.
(Optional) Check List Alert Channels's /catalog for valid webhook app / SMTP provider codes.
Send the new channel's details.

The call

POST /api/alert-channels

Permission needed: Credential.Manage.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Step 2 & 3: A Slack webhook channel -- only the webhook fields are set, everything else stays null.
var newChannel = new CreateAlertChannelRequest(
    ChannelName: "DBA Team Slack", AlertChannelKindCode: 0 /* Webhook */,
    WebhookAppCode: 1 /* Slack, from the catalog */, WebhookUrl: "https://hooks.slack.com/services/T000/B000/xxxx",
    ToAddresses: null, DbMailProfileName: null,
    SmtpProviderCode: null, SmtpHost: null, SmtpPort: null, SmtpUseStartTls: null, SmtpFromAddress: null, SmtpFromDisplayName: null, SmtpCredentialId: null);
var response = await client.PostAsJsonAsync("/api/alert-channels", newChannel, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedIdResponse>(jsonOptions);
Console.WriteLine($"Created channel id: {created!.Id}");

record CreateAlertChannelRequest(string ChannelName, byte AlertChannelKindCode, byte? WebhookAppCode, string? WebhookUrl,
    string? ToAddresses, string? DbMailProfileName,
    byte? SmtpProviderCode, string? SmtpHost, int? SmtpPort, bool? SmtpUseStartTls, string? SmtpFromAddress, string? SmtpFromDisplayName, int? SmtpCredentialId);
record CreatedIdResponse(int Id);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2 & 3: A Slack webhook channel. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newChannel = @{
    ChannelName = "DBA Team Slack"; AlertChannelKindCode = 0
    WebhookAppCode = 1; WebhookUrl = "https://hooks.slack.com/services/T000/B000/xxxx"
    ToAddresses = $null; DbMailProfileName = $null
    SmtpProviderCode = $null; SmtpHost = $null; SmtpPort = $null; SmtpUseStartTls = $null; SmtpFromAddress = $null; SmtpFromDisplayName = $null; SmtpCredentialId = $null
} | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-channels" `
    -Method Post -Body $newChannel -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Created channel id: $($created.id)"

An SMTP email channel instead sets AlertChannelKindCode to the SMTP kind, ToAddresses, and the whole Smtp* block (SmtpCredentialId from List Credentials, filtered to SmtpAuth-type ones). A Database Mail channel just sets ToAddresses and DbMailProfileName.

What you get back

201 Created:

{ "id": 5 }

Codes this call can return

See API Response Codes for what each one means in general. For this specific call:

201 -- created.
403 -- you don't have Credential.Manage.

There's no coded validation for a bad AlertChannelKindCode/WebhookAppCode/SmtpProviderCode in this endpoint -- an invalid value isn't caught with a friendly 400, so check the catalog for valid codes before sending one.

What gets audited

Recorded as AlertChannel / Create Alert Channel, with the channel name, kind, and the non-secret SMTP/webhook-app settings in the after-state. The webhook URL is never written to the audit trail, plaintext or encrypted.

Create an Alert Channel Print