Notification Channels

Notification channels let you receive real-time alerts when webhook deliveries fail, routes recover, or circuit breakers trip. Send notifications to Slack, Microsoft Teams, Discord, PagerDuty, email, or custom webhooks.

Channel Types

Type	Description	Best For
Slack	Send Block Kit messages to Slack channels	Team alerts
Microsoft Teams	Send Adaptive Cards to Teams channels	Enterprise team alerts
Discord	Send embedded messages to Discord channels	Developer/community alerts
PagerDuty	Create incidents via Events API v2	On-call incident management
Email	Send emails to multiple recipients	On-call notifications
Webhook	POST to custom HTTP endpoints	Integration with monitoring tools

Creating Channels

Slack Channel

bash

curl -X POST "https://api.hookbase.app/api/notification-channels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ops Slack",
    "type": "slack",
    "config": {
      "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    }
  }'

To get a Slack webhook URL:

Go to your Slack workspace settings
Navigate to Apps → Incoming Webhooks
Create a new webhook and select a channel

Email Channel

bash

curl -X POST "https://api.hookbase.app/api/notification-channels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On-Call Team",
    "type": "email",
    "config": {
      "emails": ["[email protected]", "[email protected]"]
    }
  }'

Custom Webhook Channel

bash

curl -X POST "https://api.hookbase.app/api/notification-channels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monitoring Webhook",
    "type": "webhook",
    "config": {
      "url": "https://your-service.com/alerts",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer whr_your_api_key"
      },
      "hmacSecret": "optional-signing-secret"
    }
  }'

Microsoft Teams Channel

bash

curl -X POST "https://api.hookbase.app/api/notification-channels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DevOps Team",
    "type": "teams",
    "config": {
      "webhookUrl": "https://outlook.office.com/webhook/..."
    }
  }'

To get a Microsoft Teams webhook URL:

Open your Teams channel
Click the ... menu → Connectors
Find Incoming Webhook and click Configure
Name the webhook and click Create
Copy the webhook URL

Teams notifications use Adaptive Cards with color-coded status, structured data fields, and a link to your Hookbase dashboard.

PagerDuty Channel

bash

curl -X POST "https://api.hookbase.app/api/notification-channels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On-Call Paging",
    "type": "pagerduty",
    "config": {
      "routingKey": "your-32-character-integration-key",
      "severity": "error",
      "customService": "Hookbase Webhooks"
    }
  }'

Config options:

Field	Required	Description
`routingKey`	Yes	32-character integration key from PagerDuty
`severity`	No	Default severity: `critical`, `error`, `warning`, or `info`
`customService`	No	Custom service name (defaults to "Hookbase")

To get a PagerDuty integration key:

Go to Services → Select or create a service
Click Integrations → Add Integration
Select Events API v2
Copy the Integration Key (32 characters)

PagerDuty Features

Automatic Incident Management:

Deduplication: Incidents are deduplicated by route/cron ID, preventing duplicate alerts
Auto-Resolve: When a route recovers, the incident is automatically resolved
Severity Mapping: Circuit breaker events use "critical" severity, failures use "error"

Hookbase Event	PagerDuty Action	Severity
Delivery Failure	Trigger	error (configurable)
Circuit Opened	Trigger	critical
Cron Failure	Trigger	error (configurable)
Recovery	Resolve	info
Circuit Closed	Resolve	info

Discord Channel

bash

curl -X POST "https://api.hookbase.app/api/notification-channels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dev Alerts",
    "type": "discord",
    "config": {
      "webhookUrl": "https://discord.com/api/webhooks/...",
      "username": "Hookbase Bot",
      "avatarUrl": "https://hookbase.app/logo.png"
    }
  }'

Config options:

Field	Required	Description
`webhookUrl`	Yes	Discord webhook URL
`username`	No	Bot display name (defaults to webhook name)
`avatarUrl`	No	Bot avatar image URL

To create a Discord webhook:

Go to your Discord channel
Click the gear icon → Integrations → Webhooks
Click New Webhook
Name it and copy the Webhook URL

Discord notifications use embedded messages with color-coded status (red for failures, green for success), inline fields, and timestamps.

Rate Limiting

Discord webhooks have rate limits (~30 requests/minute). For high-volume alerting, consider using PagerDuty or a custom webhook with batching.

Linking Channels to Routes

Channels must be linked to specific routes to receive notifications:

bash

curl -X POST "https://api.hookbase.app/api/notification-channels/{channelId}/routes" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "routeId": "{routeId}",
    "notifyOnFailure": true,
    "notifyOnRecovery": true,
    "notifyOnCircuitOpen": true
  }'

Notification Triggers

Trigger	Description
`notifyOnFailure`	When consecutive delivery failures exceed the threshold
`notifyOnRecovery`	When a failing route starts succeeding again
`notifyOnCircuitOpen`	When the circuit breaker trips open

Managing Channels via Dashboard

Navigate to Settings → Notifications
Click Add Channel
Select the channel type
Configure the channel settings
Click Create

Linking Routes in Dashboard

Find your channel in the list
Click the expand arrow to see linked routes
Click Link Route
Select a route and choose notification triggers
Click Link Route

Testing Channels

Send a test notification to verify your configuration:

Via API

bash

curl -X POST "https://api.hookbase.app/api/notification-channels/{channelId}/test" \
  -H "Authorization: Bearer {token}"

Via Dashboard

Navigate to Settings → Notifications
Find the channel
Click the Test button

Notification Payloads

Slack Message Format

json

{
  "text": "Webhook Alert",
  "attachments": [{
    "color": "#ff0000",
    "title": "Delivery Failures",
    "text": "Route 'GitHub → Slack' has failed 5 consecutive times",
    "fields": [
      { "title": "Route", "value": "GitHub → Slack", "short": true },
      { "title": "Destination", "value": "https://example.com/webhook", "short": true },
      { "title": "Last Error", "value": "Connection timeout", "short": false }
    ],
    "ts": 1705312200
  }]
}

Custom Webhook Payload

json

{
  "type": "delivery_failure",
  "route": {
    "id": "route_123",
    "name": "GitHub → Slack"
  },
  "destination": {
    "id": "dest_456",
    "url": "https://example.com/webhook"
  },
  "consecutiveFailures": 5,
  "lastError": "Connection timeout",
  "timestamp": "2024-01-15T10:30:00Z"
}

Email Format

Subject: [Hookbase] Delivery Failures: GitHub → Slack

Body includes route details, failure count, last error, and links to the dashboard.

Teams Adaptive Card Format

json

{
  "type": "message",
  "attachments": [{
    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": {
      "type": "AdaptiveCard",
      "version": "1.4",
      "body": [
        {
          "type": "TextBlock",
          "text": "Route Delivery Failed",
          "size": "Large",
          "weight": "Bolder",
          "color": "attention"
        },
        {
          "type": "FactSet",
          "facts": [
            { "title": "Route", "value": "GitHub → Slack" },
            { "title": "Destination", "value": "slack-webhook" },
            { "title": "Consecutive Failures", "value": "5" }
          ]
        }
      ],
      "actions": [
        {
          "type": "Action.OpenUrl",
          "title": "View in Dashboard",
          "url": "https://app.hookbase.app/..."
        }
      ]
    }
  }]
}

PagerDuty Events API v2 Format

json

{
  "routing_key": "your-routing-key",
  "event_action": "trigger",
  "dedup_key": "hookbase-route-route_123",
  "payload": {
    "summary": "Route \"GitHub → Slack\" delivery failed: Connection timeout",
    "source": "slack-webhook",
    "severity": "error",
    "timestamp": "2024-01-15T10:30:00Z",
    "component": "Hookbase",
    "group": "webhook-delivery",
    "class": "route_failure",
    "custom_details": {
      "route": "GitHub → Slack",
      "source": "GitHub",
      "destination": "slack-webhook",
      "consecutive_failures": "5",
      "dashboard_url": "https://app.hookbase.app/..."
    }
  }
}

Discord Embed Format

json

{
  "embeds": [{
    "title": "Route Delivery Failed",
    "color": 15548997,
    "fields": [
      { "name": "Route", "value": "GitHub → Slack", "inline": true },
      { "name": "Source", "value": "GitHub", "inline": true },
      { "name": "Failures", "value": "5 consecutive", "inline": true }
    ],
    "url": "https://app.hookbase.app/...",
    "footer": { "text": "Hookbase" },
    "timestamp": "2024-01-15T10:30:00.000Z"
  }],
  "username": "Hookbase Bot"
}

HMAC Signing (Webhook Channels)

For webhook channels, you can configure HMAC signing for security:

bash

curl -X POST "https://api.hookbase.app/api/notification-channels" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure Webhook",
    "type": "webhook",
    "config": {
      "url": "https://your-service.com/alerts",
      "method": "POST",
      "hmacSecret": "your-secret-key"
    }
  }'

The signature is sent in the X-Hookbase-Signature header as a hex-encoded HMAC-SHA256.

Verify in your service:

javascript

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Best Practices

Set up before issues occur: Don't wait for failures to configure notifications
Use multiple channels: Send to both Slack and email for critical routes
Configure recovery alerts: Know when issues are resolved, not just when they start
Test regularly: Verify channels work before you need them
Don't over-notify: Choose appropriate triggers to avoid alert fatigue

Managing Linked Routes

View linked routes

bash

curl -X GET "https://api.hookbase.app/api/notification-channels/{channelId}/routes" \
  -H "Authorization: Bearer {token}"

Update link settings

bash

curl -X PATCH "https://api.hookbase.app/api/notification-channels/{channelId}/routes/{routeId}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notifyOnFailure": true,
    "notifyOnRecovery": false,
    "notifyOnCircuitOpen": true
  }'

Unlink a route

bash

curl -X DELETE "https://api.hookbase.app/api/notification-channels/{channelId}/routes/{routeId}" \
  -H "Authorization: Bearer {token}"

Notification Channels ​

Channel Types ​

Creating Channels ​

Slack Channel ​

Email Channel ​

Custom Webhook Channel ​

Microsoft Teams Channel ​

PagerDuty Channel ​

PagerDuty Features ​

Discord Channel ​

Linking Channels to Routes ​

Notification Triggers ​

Managing Channels via Dashboard ​

Linking Routes in Dashboard ​

Testing Channels ​

Via API ​

Via Dashboard ​

Notification Payloads ​

Slack Message Format ​

Custom Webhook Payload ​

Email Format ​

Teams Adaptive Card Format ​

PagerDuty Events API v2 Format ​

Discord Embed Format ​

HMAC Signing (Webhook Channels) ​

Best Practices ​

Managing Linked Routes ​

View linked routes ​

Update link settings ​

Unlink a route ​

Notification Channels

Channel Types

Creating Channels

Slack Channel

Email Channel

Custom Webhook Channel

Microsoft Teams Channel

PagerDuty Channel

PagerDuty Features

Discord Channel

Linking Channels to Routes

Notification Triggers

Managing Channels via Dashboard

Linking Routes in Dashboard

Testing Channels

Via API

Via Dashboard

Notification Payloads

Slack Message Format

Custom Webhook Payload

Email Format

Teams Adaptive Card Format

PagerDuty Events API v2 Format

Discord Embed Format

HMAC Signing (Webhook Channels)

Best Practices

Managing Linked Routes

View linked routes

Update link settings

Unlink a route