Webhooks

Our platform allows you to create custom webhook triggers that deliver real-time notifications to your device. These webhooks are designed to be flexible, allowing you to tailor them to your specific needs and integrate seamlessly with your existing systems.

Webhook Structure

The base URL for our webhook triggers is:

https://justshare.me/trigger/alert/?code={your-host-code}

To activate a trigger, you'll append query parameters to this URL. The core parameter is code, which is mandatory. Additionally, you can include optional parameters like user, ip, and message.

Here's a breakdown of the parameters:

• code={code} (Mandatory):
  

  • This parameter represents a unique, system-generated identifier for your trigger. When you create a new host within our app, a unique code is automatically assigned to that host.
  • This ensures that each host has a distinct trigger, preventing conflicts and enabling precise notification routing.
  • Example: code=abcd1234
    
    

• user={user} (Optional):
  

  • This parameter allows you to include user-specific information, such as a username or user ID.
  • Example: user=john.doe
    
    

• ip={ip} (Optional):
  

  • This parameter includes the IP address associated with the event, which can be useful for security or logging purposes.
  • Example: ip=192.168.1.1
    
    

• message={message} (Optional):
  

  • This parameter includes the IP address associated with the event, which can be useful for security or logging purposes.
  • Example: message=Hello%20from%20the%20oteher%20side!
    
    

Examples:

Valid trigger URL:

https://justshare.me/trigger/alert/?code=abcd1234&user=alice&ip=192.168.1.1

Using curl to send a trigger incuding a message:

curl -G --data-urlencode 'message=Hello from the other side!' 'https://justshare.me/trigger/alert/?code=abcd1234&user=adele'

Setting Up and Customizing Webhooks

1. Create a New Host (Automatic Code Generation):
   • Within our app, create a new host. The system will automatically generate a unique code for this host.
   • This code will be displayed to you within the app, and should be copied and saved for later use.
2. Optional Parameters:
   • Determine if you need to include user, ip, or message parameters. These parameters can provide valuable context for your notifications.
3. Construct the URL:
   • Combine the base URL with the necessary query parameters to create your complete webhook URL.
4. Notification Templates:
   • Within our app, you can create notification templates that define the content of your notifications.
   • Use placeholders like [name], [user], [ip], and [message] within your templates to dynamically insert the values from your webhook parameters.
   • [name] is a placeholder refering to the name of your host in the app.
   • Example: a title of: "Alert: [name] for User: [user] At [ip]"
5. Trigger the Webhook:
   • Implement the webhook URL in your application or system. When the relevant event occurs, your system should send an HTTP GET request to the webhook URL.
6. Receive the Notification:
   • Your device will receive the notification, which will contain the customized data based on your template and the provided parameters.

Use Cases

Here are a few examples of how you can use webhook triggers:

• Security Alerts:
  • Trigger a webhook when a suspicious login attempt is detected.
  • Include the user's IP address for investigation.
• System Monitoring:
  • Use webhooks to monitor system performance and receive alerts when specific thresholds are exceeded.
  • You could use the [name] placeholder to denote which server the alert is coming from.
• Custom Notifications:
  • Use the code parameter to alert when a specific file has been shared, or when a document has been edited.
• User activity tracking:
  • Log user actions, like file downloads, or page visits, with the code, user, and ip parameters.
• Backup Completion Notifications:
  • Receive instant notifications via webhooks when backup or restore operations are completed, ensuring timely awareness of data protection activities.
• Deployment Success/Failure Notifications:
  • Track deployment progress and identify issues early by configuring webhooks to trigger at key stages of your CI/CD pipeline, providing real-time success or failure feedback.

Tips for Success

• Use descriptive names for your hosts in the app.
• Use the optional parameters to provide as much context as possible.
• Customize your notifications with placeholders to provide additional content.
• Test your webhook triggers thoroughly to ensure they are working correctly.

Triggering a Webhook on SSH Login

This guide outlines how to configure a Linux server to trigger a Host Alerts webhook when a user logs in via SSH. This is useful for security alerts, or automating tasks upon login.

Prerequisites:

• Linux System: This guide assumes a Linux-based system (e.g., Ubuntu).
• Basic Shell Scripting Knowledge: Familiarity with shell scripting is necessary.
• Root or sudo access: You'll need elevated privileges to modify system files.

Step 1: Edit the PAM Authentication File

Modify the PAM (Pluggable Authentication Module) SSH session file to call a script when a user logs in.

Run this command to edit the PAM configuration for SSH:

sudo nano /etc/pam.d/sshd

Add this line at the end:

session    optional     pam_exec.so /opt/ssh-webhook.sh

Step 2: Create the Webhook Script

Create a script at /opt/ssh-webhook.sh that will send a request to your webhook URL.

#!/bin/bash

# Webhook settings
WEBHOOK_URL="https://justshare.me/trigger/alert"
CODE="your-host-code"

# Extract username and IP
USER_NAME="$PAM_USER"
USER_IP="$PAM_RHOST"

# Send the request
curl -G --data-urlencode "code=$CODE" --data-urlencode "user=$USER_NAME" --data-urlencode "ip=$USER_IP" "$WEBHOOK_URL"

Step 3: Make the Script Executable

Run:

sudo chmod +x /opt/ssh-webhook.sh

Step 4: Restart SSH Service

To apply the changes, restart SSH:

sudo systemctl restart sshd

How It Works

• Every time someone logs into SSH, PAM will execute the script.
• The script extracts the username ($PAM_USER) and IP address ($PAM_RHOST).
• It then makes a GET request to your webhook with the required parameters.

Triggering a Webhook on Wordpress Login

This guide outlines how to configure your Wordpress installation to trigger a Host Alerts webhook when a user logs into the admin dashboard, Providing immediate notification of potential security events.

Prerequisites:

• Wordpress: This guide assumes a Wordpress 6.0 or later installation.
• Admin access: You'll need administator privileges to install plugins.

Installation

1. Download the Plugin:

   • Locate and download the Host Alerts Wordpress Plugin file from the the Github repository.

2. Upload via WordPress Plugin Upload:

   • Log in to your WordPress admin dashboard.
   • Navigate to "Plugins" > "Add New."
   • Click the "Upload Plugin" button at the top of the page.
   • Click "Choose File" and select the plugin.zip file you downloaded.
   • Click "Install Now."

3. Activate the Plugin:

   • Log in to your WordPress admin dashboard.
   • Navigate to the "Plugins" page.
   • Find the Host Alerts plugin you just uploaded in the list of available plugins.
   • Click the "Activate" button next to the plugin's name.

Using the Plugin

1. Obtain Your Host Code:

   • Download and open the Host Alerts iOS app.
   • Create a new host and copy your unique host code within the app.

2. Navigate to WordPress Settings:

   • Log in to your WordPress admin dashboard.
   • Go to "Settings" > "Host Alerts Webhook."

3. Enter the Host Code:

   • Paste the host code you copied from the Host Alerts app into the "Code" field.

4. Save Changes:

   • Click the "Save Changes" button to apply the settings.

Source Code

We're committed to transparency and community contribution. The full source code for this plugin is available on GitHub.

• host-alerts-wordpress-plugin