Guide: Send Alerts from Bash using Webhooks

One of the most powerful ways to use AlertHub is to integrate it into your system scripts. Whether you are running nightly backups, cron jobs, or CI/CD deployments, receiving a notification when something goes wrong (or right) is crucial.

In this tutorial, we will set up a Linux environment to send alerts securely using environment variables.

1. Get Your Project Key

First, you need your project credentials:

1. Go to your AlertHub dashboard.
2. Create a new Project (or use an existing one).
3. Copy the Secret Key (usually starts with sk_...).

2. Configure the Environment Variable

To avoid hardcoding your secret key in every script, it is best practice to store it in an environment variable.

Open your terminal and run:

export ALERTHUB_KEY="your_secret_key_here"

To make it permanent, add that line to your ~/.bashrc or ~/.zshrc file.

3. Send an Alert with cURL

Now we can use curl to send an HTTP POST request to the AlertHub Ingestion API. We will use the $ALERTHUB_KEY variable we just defined.

Copy and paste this command:

curl -X POST https://api.thealerthub.com/sendAlert \
  -H "Content-Type: application/json" \
  -d '{
    "ah_key": "'"$ALERTHUB_KEY"'",
    "ah_title": "Backup Completed",
    "ah_description": "The database backup finished successfully.",
    "ah_level": "info",
    "ah_source": "BackupScripts"
  }'

What is happening here?

• -X POST: Indicates that this is a POST request.
• -H "Content-Type:...": Tells the server we are sending JSON data.
• "ah_key": "'"$ALERTHUB_KEY"'": Here is the bash trick. We use double and single quotes to insert the variable value inside the JSON string.

Bonus: Advanced Bash Function

To make this tool even more powerful, add this function to your .bashrc or .zshrc. It supports flags (-t, -d, -l, -s), interactive configuration, and key rotation.

alerthub_alert() {
    local title=""
    local desc=""
    local level="info"
    local source="BashScript"
    local change_key=false

    # Parse arguments
    while [[ "$#" -gt 0 ]]; do
        case $1 in
            -t) title="$2"; shift ;;
            -d) desc="$2"; shift ;;
            -l) level="$2"; shift ;;
            -s) source="$2"; shift ;;
            --change-project-key) change_key=true ;;
            *) echo "Unknown parameter: $1"; return 1 ;;
        esac
        shift
    done

    # Check for API Key or Key Change request
    if [[ "$change_key" == true ]] || [[ -z "$ALERTHUB_KEY" ]]; then
        if [[ -z "$ALERTHUB_KEY" ]]; then
            echo "ALERTHUB_KEY not found."
        fi
        
        echo -n "Enter your AlertHub Secret Key (Press Enter to cancel): "
        read -r input_key
        
        if [[ -n "$input_key" ]]; then
            export ALERTHUB_KEY="$input_key"
            echo "✅ ALERTHUB_KEY set for this session."
            
            # Optional: Ask to persist
            echo -n "Do you want to save this to your shell config? (y/n): "
            read -r save_persist
            if [[ "$save_persist" == "y" ]]; then
                echo "export ALERTHUB_KEY=\"$input_key\"" >> ~/$(basename $SHELL)rc
                echo "Saved to ~/$(basename $SHELL)rc"
            fi
        elif [[ -z "$ALERTHUB_KEY" ]]; then
             echo "❌ Key is required to send alerts. Exiting."
             return 1
        fi
    fi

    # Exit if we only wanted to change the key
    if [[ "$change_key" == true && -z "$title" ]]; then return 0; fi

    # Validation
    if [[ -z "$title" ]]; then
        echo "Error: Title is required. Use -t \"My Title\""
        return 1
    fi

    # Send Request
    curl -s -X POST https://api.thealerthub.com/sendAlert \
      -H "Content-Type: application/json" \
      -d "{
        \"ah_key\": \"$ALERTHUB_KEY\",
        \"ah_title\": \"$title\",
        \"ah_description\": \"$desc\",
        \"ah_level\": \"$level\",
        \"ah_source\": \"$source\"
      }" > /dev/null
      
    if [ $? -eq 0 ]; then
        echo "Alert sent successfully! 🚀"
    else
        echo "Failed to send alert."
    fi
}

Usage Examples

1. Verify or Set Key:

alert --change-project-key

2. Send a simple alert:

alert -t "Deployment Finished"

3. Send a full critical alert:

alert -t "Database Error" -d "Connection timeout on 192.168.1.5" -l "critical"