Webhooks

This feature is only available on Enterprise plan.

Webhooks allow you to notify external systems when events occur in your GoRules project. Configure webhooks to trigger CI/CD pipelines, send notifications, or integrate with third-party services when commits are made, releases are created, or change requests are updated.

Webhook list

The Webhooks page displays all configured webhooks for your project. Access it from Settings → Webhooks.

List columns

Column	Description
Description	Webhook name or description
Target	Destination URL or repository
Events	Number of events the webhook listens to
Status	Current state (active or inactive)
Actions	View logs, update, or delete the webhook

Webhook types

GoRules supports three webhook types for different integration scenarios.

REST Webhook

Send HTTP POST requests to any URL when events occur. Ideal for custom integrations, notification services, or internal APIs. Configuration:

URL: The endpoint that receives webhook payloads
Signing secret: Generated automatically for payload verification

GitHub

Trigger GitHub Actions workflows directly from GoRules events. Requires a configured GitHub integration. Configuration:

Repository: Select from connected GitHub repositories
Target Branch: Branch to dispatch the workflow on (e.g., main)
Workflow ID: The workflow filename or ID (e.g., deploy.yml or 12345678)

GitLab

Trigger GitLab CI/CD pipelines from GoRules events. Requires a configured GitLab integration. Configuration:

Repository: Select from connected GitLab repositories

GitHub and GitLab webhooks require integrations to be configured first. Click “Configure Integrations” in the webhook form to set up the connection.

Available events

Select which events trigger the webhook.

Commits (main branch)

Event	Description
Commit Created	A new commit is made to the main branch

Releases

Event	Description
Release Created	A new release is created
Draft Release Published	A draft release is published
Release Deployed	A release is deployed to an environment

Change Requests

Event	Description
Change Request Opened	A new change request is created
Change Request Updated	A change request is modified
Change Request Completed	A change request is merged
Change Request Cancelled	A change request is abandoned
Change Request Comment	A comment is added to a change request

Creating a webhook

Go to Settings → Webhooks
Click “Create webhook”
Enter a description
Select the webhook type (REST Webhook, GitHub, or GitLab)
Configure the target:
- For REST: Enter the destination URL
- For GitHub/GitLab: Select repository and workflow details
Select the events to listen for
Click “Create”

For REST webhooks, a signing secret is generated and displayed once after creation. Copy it immediately as it won’t be shown again.

Signing secret

REST webhooks include a signing secret for verifying payload authenticity. The secret is used to generate an HMAC signature sent with each request.

Testing webhooks

Before relying on a webhook in production, send a test request.

Open the create or update webhook form
In the “Test Webhook” section, select an event type
Click “Send Test”

The test uses a sample payload with the test secret grl_whsec_test to verify your endpoint is reachable.

Webhook logs

View the history of webhook deliveries and troubleshoot issues.

Accessing logs

Go to Settings → Webhooks
Click “View Logs” on the webhook row

Log details

Each log entry shows:

Field	Description
Event Type	The event that triggered the delivery
Status	SUCCESS or failure status
Attempted At	Timestamp of the delivery attempt

Expanded log view

Click a log entry to see detailed information: Request tab:

URL: The destination endpoint
Payload: JSON data sent to the endpoint
Headers: Request headers including authentication

Response tab:

Status code: HTTP response code (e.g., 204)
Body: Response content from the endpoint
Completion time: Request duration in milliseconds

Retrying failed deliveries

If a delivery fails, click “Retry” to resend the webhook with the same payload.

Managing webhooks

Updating a webhook

Click the three-dot menu on the webhook row
Select “Update”
Modify the configuration
Click “Update”

You can change the description, events, and target configuration. The webhook type cannot be changed after creation.

Enabling or disabling

Toggle the “Active” switch in the update form to enable or disable a webhook without deleting it.

Deleting a webhook

Click the three-dot menu on the webhook row
Select “Delete”
Confirm the deletion

Deleting a webhook is permanent. Any external systems relying on the webhook will stop receiving notifications.

Webhook payload

Webhook payloads include event details in JSON format.

Payload structure

{
  "eventId": "dea48f7b-2cca-4113-a00d-eb8c0fb06a5d",
  "eventType": "release.created",
  ...
}

The payload content varies by event type and includes relevant data such as commit information, release details, or change request metadata.

Request headers

Header	Value
Content-Type	application/json
User-Agent	GoRules-Webhook/1.0
X-Webhook-Id	Unique webhook identifier
X-Webhook-Event	Event type (e.g., release.created)
Authorization	Bearer token (for GitHub/GitLab)

Verifying webhook signatures

REST webhooks include a signing secret for verifying payload authenticity. Each request contains an X-Webhook-Signature header with an HMAC-SHA256 signature of the request body.

Signature format

The signature header uses the format sha256=<hex-encoded-hash>. Verify this against your own HMAC calculation using the webhook’s signing secret.

Node.js example

const crypto = require('crypto');

const WEBHOOK_SECRET = 'your_webhook_secret';

function verifyWebhookSignature(receivedSignature, rawBody, secret) {
    if (!receivedSignature || !rawBody || !secret) {
        return false;
    }

    try {
        // Extract the hash part from 'sha256=<hash>' format
        const signatureHash = receivedSignature.split('=')[1] || receivedSignature;

        const hmac = crypto.createHmac('sha256', secret);
        hmac.update(rawBody);
        const expectedSignature = hmac.digest('hex');

        // Use timing-safe comparison to prevent timing attacks
        return crypto.timingSafeEqual(
            Buffer.from(signatureHash, 'hex'),
            Buffer.from(expectedSignature, 'hex')
        );
    } catch (error) {
        console.error('Signature verification error:', error);
        return false;
    }
}

// Express route handler
router.post('/webhook', async (req, res) => {
    const signature = req.headers['x-webhook-signature'];
    const rawBody = req.rawBody;

    // Verify signature
    if (!verifyWebhookSignature(signature, rawBody, WEBHOOK_SECRET)) {
        return res.status(401).send('Unauthorized');
    }

    // Process webhook
    const payload = req.body;
    console.log('Valid webhook:', payload.eventType);

    res.status(200).send('OK');
});

You must use the raw request body for signature verification, not the parsed JSON. If you’re using body-parser middleware, configure it to preserve the raw body:

app.use(express.json({
    verify: (req, res, buf) => {
        req.rawBody = buf.toString();
    }
}));

Verification steps

Extract the X-Webhook-Signature header from the request
Get the raw request body (before JSON parsing)
Compute HMAC-SHA256 of the raw body using your signing secret
Compare the computed hash with the received signature using a timing-safe comparison
Reject the request if signatures don’t match

Setup

Build

Deploy

Administration

Webhook list

List columns

Webhook types

REST Webhook

GitHub

GitLab

Available events

Commits (main branch)

Releases

Change Requests

Creating a webhook

Signing secret

Testing webhooks

Webhook logs

Accessing logs

Log details

Expanded log view

Retrying failed deliveries

Managing webhooks

Updating a webhook

Enabling or disabling

Deleting a webhook

Webhook payload

Payload structure

Request headers

Verifying webhook signatures

Signature format

Node.js example

Verification steps

​Webhook list

​List columns

​Webhook types

​REST Webhook

​GitHub

​GitLab

​Available events

​Commits (main branch)

​Releases

​Change Requests

​Creating a webhook

​Signing secret

​Testing webhooks

​Webhook logs

​Accessing logs

​Log details

​Expanded log view

​Retrying failed deliveries

​Managing webhooks

​Updating a webhook

​Enabling or disabling

​Deleting a webhook

​Webhook payload

​Payload structure

​Request headers

​Verifying webhook signatures

​Signature format

​Node.js example

​Verification steps

Webhook list

List columns

Webhook types

REST Webhook

GitHub

GitLab

Available events

Commits (main branch)

Releases

Change Requests

Creating a webhook

Signing secret

Testing webhooks

Webhook logs

Accessing logs

Log details

Expanded log view

Retrying failed deliveries

Managing webhooks

Updating a webhook

Enabling or disabling

Deleting a webhook

Webhook payload

Payload structure

Request headers

Verifying webhook signatures

Signature format

Node.js example

Verification steps