Run a shell script from a webhook call

If you've ever found yourself thinking I wish I could just run this script via curl, then webhooks are about to become your new best friend. In this tutorial, we'll explore how to transform CTFreak into a powerful webhook server that can trigger your automation tasks with nothing more than an HTTP request.

The beauty of this approach? You can integrate your scripts and playbooks into virtually any workflow, whether it's responding to GitHub events, processing form submissions, or reacting to monitoring alerts. Let's dive in and build something practical.

What we'll build

By the end of this tutorial, you'll have a fully functional webhook endpoint that executes a Bash script with parameters passed directly through the URL. We'll then show you how this same pattern works seamlessly with Powershell scripts and Ansible playbooks.

Here's what we'll cover:

1. Adding a node to CTFreak with SSH authentication
2. Creating a parameterized Bash script task
3. Setting up an incoming webhook
4. Triggering the script via HTTP with query parameters
5. Verifying execution through the logs

Prerequisites

Before we start, make sure you have:

• A CTFreak instance up and running
• A Unix server accessible via SSH where your scripts will run
• An SSH key for connecting to the server
• Admin access to your CTFreak instance

Step 1: Adding your node

First things first, we need to tell CTFreak about the server where your scripts will execute.

Navigate to Credentials → New Credential and add your SSH key. Make sure to paste your private key in the appropriate field and give it a memorable name, something like Production server key rather than That key I found in my downloads folder.

Once your credential is saved, head over to Nodes → Internal nodes → New node to register your server. Fill in the following details:

• Name: A descriptive name for your server (e.g., webhook-runner)
• OS Family: Choose Unix for Linux servers
• Username: The SSH user CTFreak will use to connect
• Hostname: Your server's IP address or hostname
• Port: SSH port, typically 22
• Credential: Select the SSH key you just created

Click Create, then verify that the connection to your node is working by attempting to open the file explorer (via the Browse button). If you see the contents of a directory, congratulations, you're ready to move forward.

Step 2: Creating a parameterized Bash script task

Now comes the fun part. We're going to create a task that accepts parameters, which means the same webhook can behave differently based on the values you pass to it. This is where the real magic happens.

Navigate to Projects → New project if you don't already have a suitable project, or use an existing one. Let's call our project Webhook Automation for clarity.

Inside your project, click New task and select Bash Script as the task type. You'll see a form with several fields to fill out:

Name: Give your task a descriptive name like Process deployment webhook

Script: This is where you write your Bash script. For this example, we'll create a simple script that uses two parameters:

#!/bin/bash

echo "Webhook triggered with parameters:"
echo "Environment: $CTP_ENVIRONMENT"
echo "Version: $CTP_VERSION"

# Your actual deployment logic would go here
# For example:
# cd /var/www/app
# git pull origin $CTP_VERSION
# systemctl restart myapp-$CTP_ENVIRONMENT

Notice how we're using environment variables prefixed with CTP_. This is CTFreak's convention for injecting parameters into your scripts, and it works beautifully once you get used to it.

Node Set filter: Enter the node name we created earlier.

Now, let's add our parameters. Click the Add parameter button twice to create two parameters:

First parameter:

• Name: ENVIRONMENT
• Parameter type: Selector
• Options: Add values like "staging", "production"
• Default value: "staging"

Second parameter:

• Name: VERSION
• Parameter type: Text
• Default value: "main"

The beauty of this setup is that you can make the parameters as restrictive or flexible as you need. Selector types limit choices to prevent mishaps (nobody wants to accidentally deploy to production when they meant staging), while text types give you complete freedom.

Save your task, and let's move on to exposing it to the world via a webhook.

Step 3: Creating the incoming webhook

This is where CTFreak transforms from a task automation tool into a full-fledged webhook server. From the task we just created, head to Incoming webhooks → New webhook → Generic.

You'll need to configure a few things:

Name: Something descriptive like "Deployment trigger"

Enabled: Make sure this toggle is on, or you'll be wondering why nothing happens when you call it.

Save the webhook, and CTFreak will display your webhook URL along with the authentication details. It'll look something like:

https://your-ctfreak-instance/wh/VEihowf6DHiDj1C2iZtXjTI7alFxFXzVoSareJeD7EskYzx2t1InyBEB6Wuq

Copy this URL, you're about to use it.

Step 4: Triggering the webhook

Now for the moment of truth. You can trigger your webhook from anywhere that can make an HTTP request: a CI/CD pipeline, a monitoring tool, another script, or just your terminal for testing.

Here's how to call it with curl, passing our two parameters as query strings:

curl -X POST "https://your-ctfreak-instance/wh/VEihowf6DHiDj1C2iZtXjTI7alFxFXzVoSareJeD7EskYzx2t1InyBEB6Wuq?ENVIRONMENT=production&VERSION=v2.1.0"

Notice how we're passing ENVIRONMENT and VERSION as query parameters? CTFreak automatically maps these to the corresponding task parameters and injects them as environment variables (prefixed with CTP-) into your script.

You can also pass parameters as URL-encoded form submission if you prefer:

curl -X POST "https://your-ctfreak-instance/wh/VEihowf6DHiDj1C2iZtXjTI7alFxFXzVoSareJeD7EskYzx2t1InyBEB6Wuq" \
-d "ENVIRONMENT=production" \
-d "VERSION=v2.1.0"

Both methods work equally well, so use whichever fits your workflow better.

The webhook will return a response immediately, including an execution ID that you can use to check the status and logs later:

{"status":200,"executionId":"01K9STQAFNQ8MKB47F4DZ32RH7","message":"I got the payload!"}

This is perfect for asynchronous workflows where you fire off a task and check back later to see how it went.

Step 5: Verifying the execution

Let's make sure everything worked as expected. Navigate to Projects → Webhook Automation → Process deployment webhook. You should see your webhook-triggered execution at the top of the execution list.

Click on the execution ID, and on the eye icon to view the execution logs. You'll see the output from your script, including the parameter values that were passed in:

Beautiful. Your parameters made it through the HTTP request, into CTFreak, and into your script exactly as intended. This is the foundation you can build upon for much more complex workflows.

Beyond Bash: Powershell and Ansible

Here's where things get even better. The webhook pattern we just built works identically with other task types. Let me show you how.

Powershell scripts

If you're working with Windows servers, simply create a Powershell Script task instead of Bash Script task. When adding your node, set the OS Family to Windows and adjust your credentials according to the chosen connection protocol (SSH or WinRM).

Your script parameters work exactly the same way, just with Powershell syntax:

Write-Host "Webhook triggered with parameters:"
Write-Host "Environment: $env:CTP_ENVIRONMENT"
Write-Host "Version: $env:CTP_VERSION"

# Your Powershell deployment logic here

The webhook setup? Identical. The curl command? Identical. The only thing that changes is the language of your script itself.

Ansible playbooks

Running Ansible playbooks via webhooks is just as straightforward. Configure a task of type Ansible Playbook and add your parameters.

CTFreak will inject the parameters as extra variables, which you can access in your playbook like this:

- hosts: all
  tasks:
    - name: Display received parameters
      debug:
        msg: "Deploying version {{ CTP_VERSION }} to {{ CTP_ENVIRONMENT }}"

    - name: Your deployment workflow here
      # ...

Same webhook URL, same query parameters. The power of this approach is that once you understand the pattern, you can apply it to any task type CTFreak supports.

Real-world use cases

Now that you've got the basics down, let's talk about what you can actually do with this. Here are a few ideas to spark your imagination:

CI/CD integration: Trigger deployments from GitHub Actions, GitLab CI, or Jenkins after successful builds. Pass the branch name, commit hash, and environment as parameters.

Infrastructure automation: Respond to monitoring alerts by automatically scaling resources, restarting services, or running diagnostic scripts. Your monitoring tool hits a webhook, CTFreak handles the remediation.

ChatOps: Integrate with Slack or Microsoft Teams to let your team trigger common operations through chat commands. Someone types "/deploy staging v2.0" and behind the scenes, it's just a webhook call.

IoT and edge computing: Have your devices report status by hitting a webhook that triggers data processing scripts or updates dashboards.

Business process automation: Connect forms, CRM systems, or e-commerce platforms to trigger backend processes when specific events occur.

Wrapping up

You've now got a powerful webhook server that can execute arbitrary scripts with parameters, and you didn't have to write a single line of server code to make it happen. CTFreak handles the infrastructure, logging, and parameter injection, so you can focus on writing the scripts that actually do useful work.

The pattern we've explored here is deceptively simple, but it opens up endless possibilities for automation and integration. Whether you're orchestrating deployments, automating infrastructure tasks, or building custom integrations, webhooks give you a clean, HTTP-based interface to trigger your operations from anywhere.

Happy automating!