Skip to main content

Slack Webhook Integration

This tutorial shows you how to integrate FireBackup with Slack to receive real-time notifications about backup events. You'll learn to set up incoming webhooks, configure notification preferences, and create rich backup status messages.

What You'll Learn​

  • Create a Slack Incoming Webhook
  • Configure FireBackup to send notifications
  • Customize notification messages and formatting
  • Set up notification filters by event type
  • Create a dedicated #backups channel workflow

Prerequisites​

  • Slack workspace with permission to add apps
  • Access to FireBackup dashboard as an organization admin
  • At least one project configured in FireBackup

Time Required​

Approximately 15-20 minutes

Step 1: Create a Slack App​

Using Slack App Directory​

  1. Go to Slack API Apps

  2. Click Create New App

  3. Choose From scratch

  4. Configure your app:

    • App Name: FireBackup
    • Workspace: Select your workspace

  5. Click Create App

Configure Incoming Webhooks​

  1. In your app settings, go to Incoming Webhooks

  2. Toggle Activate Incoming Webhooks to On

  3. Click Add New Webhook to Workspace

  4. Select the channel for notifications (e.g., #backups or #alerts)

  5. Click Allow

  6. Copy the webhook URL:

    https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
Keep Webhook URL Secret

Treat your webhook URL like a password. Anyone with this URL can post messages to your Slack channel.

Step 2: Create a Dedicated Channel​

Create a dedicated channel for backup notifications:

  1. In Slack, click + next to Channels

  2. Create channel:

    • Name: #firebackup-alerts or #backups
    • Description: FireBackup notifications and alerts
    • Visibility: Private (recommended) or Public

  3. Add relevant team members

Channel Organization Tips​

ChannelPurpose
#firebackup-alertsAll backup notifications
#firebackup-criticalOnly failures and critical alerts
#firebackup-successSuccessful backup confirmations
#oncall-alertsCritical alerts for on-call team

Step 3: Configure FireBackup Webhook​

Using the Dashboard​

  1. Log in to FireBackup

  2. Navigate to Settings → Webhooks

  3. Click Add Webhook

  4. Configure the webhook:

    FieldValue
    NameSlack Notifications
    URLYour Slack webhook URL
    TypeSlack
    EventsSelect events to notify

  5. Select events to trigger notifications:

    EventDescription
    backup.startedBackup job started
    backup.completedBackup finished successfully
    backup.failedBackup failed
    restore.startedRestore initiated
    restore.completedRestore finished
    restore.failedRestore failed
    pitr.enabledPITR enabled for project
    schedule.createdNew schedule created
    schedule.failedScheduled backup missed

  6. Click Test Webhook to verify

  7. Click Save

Using the API​

curl -X POST https://api.firebackup.io/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Notifications",
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
    "type": "slack",
    "events": [
      "backup.completed",
      "backup.failed",
      "restore.completed",
      "restore.failed"
    ],
    "enabled": true
  }'

Step 4: Customize Notification Messages​

Default Message Format​

FireBackup sends rich Slack messages with Block Kit formatting:

Example Message:

  • Header: 🟢 Backup Completed Successfully
  • Project: Production App
  • Type: Full Backup
  • Duration: 4m 32s
  • Size: 125.4 MB
  • Storage: AWS S3 (us-east-1)
  • Actions: [View Details] [Download]

Message Templates​

FireBackup uses these templates for different events:

Backup Completed:

{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "✅ Backup Completed Successfully",
        "emoji": true
      }
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Project:*\n{{project.name}}"
        },
        {
          "type": "mrkdwn",
          "text": "*Type:*\n{{backup.type}}"
        },
        {
          "type": "mrkdwn",
          "text": "*Duration:*\n{{backup.duration}}"
        },
        {
          "type": "mrkdwn",
          "text": "*Size:*\n{{backup.size}}"
        }
      ]
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {
            "type": "plain_text",
            "text": "View Details"
          },
          "url": "{{backup.url}}"
        }
      ]
    }
  ]
}

Backup Failed:

{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "🔴 Backup Failed",
        "emoji": true
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Project:* {{project.name}}\n*Error:* {{error.message}}"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Failed at {{timestamp}} | Retry attempt {{retry.count}} of {{retry.max}}"
        }
      ]
    }
  ]
}

Custom Message Configuration​

Configure custom messages via API:

curl -X PATCH https://api.firebackup.io/api/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageTemplates": {
      "backup.completed": {
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "✅ *{{project.name}}* backup completed\nSize: {{backup.size}} | Duration: {{backup.duration}}"
            }
          }
        ]
      },
      "backup.failed": {
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "🚨 *{{project.name}}* backup FAILED\n```{{error.message}}```"
            }
          }
        ]
      }
    }
  }'

Step 5: Set Up Event Filters​

Filter by Project​

Send notifications only for specific projects:

curl -X PATCH https://api.firebackup.io/api/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "projects": ["proj_production", "proj_staging"]
    }
  }'

Filter by Event Severity​

Create separate webhooks for different severity levels:

Critical Alerts Only (for #oncall-alerts):

{
  "events": ["backup.failed", "restore.failed", "schedule.failed"],
  "filters": {
    "severity": ["critical", "error"]
  }
}

Success Notifications (for #backups):

{
  "events": ["backup.completed", "restore.completed"],
  "filters": {
    "severity": ["info", "success"]
  }
}

Filter by Schedule​

Only notify for scheduled (not manual) backups:

{
  "filters": {
    "trigger": ["scheduled"],
    "excludeTrigger": ["manual"]
  }
}

Step 6: Advanced Slack Integration​

Slack Workflow Builder Integration​

Create a Slack workflow that triggers on FireBackup notifications:

  1. In Slack, go to Tools → Workflow Builder

  2. Click Create

  3. Choose Starts from a webhook

  4. Configure webhook variables:

    • project_name (text)
    • backup_status (text)
    • backup_size (text)
    • error_message (text)

  5. Add steps:

    • Send message to channel
    • Add conditional logic for failures
    • Tag specific users for critical alerts

  6. Publish the workflow

Using Slack's Workflow Webhook​

Update FireBackup to use the Workflow webhook:

curl -X PATCH https://api.firebackup.io/api/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/workflows/T00000000/A00000000/000000000000/XXXXX",
    "type": "slack_workflow",
    "payloadFormat": {
      "project_name": "{{project.name}}",
      "backup_status": "{{backup.status}}",
      "backup_size": "{{backup.size}}",
      "error_message": "{{error.message}}"
    }
  }'

Step 7: Test the Integration​

Send Test Notification​

  1. Go to Settings → Webhooks

  2. Find your Slack webhook

  3. Click Test

  4. Check your Slack channel for the test message

Manual API Test​

curl -X POST https://api.firebackup.io/api/v1/webhooks/whk_abc123/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "backup.completed",
    "data": {
      "project": {
        "name": "Test Project"
      },
      "backup": {
        "id": "bkp_test123",
        "type": "full",
        "size": "50 MB",
        "duration": "2m 15s"
      }
    }
  }'

Verify Webhook Delivery​

Check webhook delivery history:

curl -X GET https://api.firebackup.io/api/v1/webhooks/whk_abc123/deliveries \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "deliveries": [
    {
      "id": "del_abc123",
      "event": "backup.completed",
      "status": "delivered",
      "statusCode": 200,
      "timestamp": "2024-01-15T10:30:45Z",
      "duration": 245
    }
  ]
}

Multiple Channel Setup​

Architecture for Multiple Channels​

Configuration Example​

# Webhook 1: All events to #backups
curl -X POST https://api.firebackup.io/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Slack - All Events",
    "url": "https://hooks.slack.com/services/T.../B.../backups-channel",
    "type": "slack",
    "events": ["*"]
  }'

# Webhook 2: Failures only to #oncall
curl -X POST https://api.firebackup.io/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Slack - Failures Only",
    "url": "https://hooks.slack.com/services/T.../B.../oncall-channel",
    "type": "slack",
    "events": ["backup.failed", "restore.failed", "schedule.failed"]
  }'

# Webhook 3: Production projects only
curl -X POST https://api.firebackup.io/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Slack - Production",
    "url": "https://hooks.slack.com/services/T.../B.../prod-ops",
    "type": "slack",
    "events": ["backup.completed", "backup.failed"],
    "filters": {
      "projects": ["proj_production"]
    }
  }'

Troubleshooting​

Notifications Not Arriving​

Check webhook status:

curl -X GET https://api.firebackup.io/api/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Verify:

  • enabled: true
  • url is correct
  • Events are selected

Check delivery history:

curl -X GET https://api.firebackup.io/api/v1/webhooks/whk_abc123/deliveries?status=failed \
  -H "Authorization: Bearer YOUR_API_KEY"

"404 Not Found" Errors​

Cause: Webhook URL is invalid or app was removed

Solution:

  1. Go to Slack API Apps
  2. Verify your app exists
  3. Check Incoming Webhooks are still active
  4. Generate a new webhook URL if needed

"403 Forbidden" Errors​

Cause: Webhook was revoked or channel permissions changed

Solution:

  1. Reinstall the Slack app to the channel
  2. Generate a new webhook URL
  3. Update the URL in FireBackup

Rate Limiting​

Cause: Too many notifications in short period

Solution:

  1. Slack limits to 1 message per second per webhook
  2. Batch notifications or reduce event frequency
  3. Use multiple webhooks for high-volume scenarios

Best Practices​

Do's​

  • ✅ Use separate webhooks for different severity levels
  • ✅ Create dedicated channels for backup notifications
  • ✅ Include actionable links in messages
  • ✅ Test webhooks after configuration changes
  • ✅ Monitor webhook delivery status regularly

Don'ts​

  • ❌ Share webhook URLs publicly
  • ❌ Send all events to high-traffic channels
  • ❌ Ignore failed webhook deliveries
  • ❌ Use personal DM channels for team alerts

Next Steps​

Last updated on