> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Automate workflows by sending event notifications to external services.

<Note>
  This feature is available on eligible plans.
</Note>

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 four 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
* Target Branch: Branch to run the pipeline on (e.g., `main`)

### Azure DevOps

Queue Azure Pipelines runs from GoRules events. Requires a configured Azure DevOps integration.

**Configuration:**

* Repository: Select from connected repositories (`project/repository`)
* Target Branch: Branch to run against (e.g., `main`)
* Pipeline: The pipeline to queue

<Note>
  The Azure pipeline must declare a queue-time-overridable `GRL_PAYLOAD` variable, or the queue request is rejected on newer organizations. See the [Azure DevOps CI/CD guide](/developers/cicd/azure-devops#2-declare-the-queue-time-variable).
</Note>

<Note>
  GitHub, GitLab, and Azure DevOps webhooks require integrations to be configured first. Click "Configure Integrations" in the webhook form to set up the connection. For end-to-end pipeline examples - pulling the rules artifact and publishing it to object storage - see the CI/CD integration guides for [GitHub Actions](/developers/cicd/github-actions), [GitLab CI](/developers/cicd/gitlab-ci), and [Azure DevOps](/developers/cicd/azure-devops).
</Note>

## 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

1. Go to Settings → Webhooks
2. Click "Create webhook"
3. Enter a description
4. Select the webhook type (REST Webhook, GitHub, GitLab, or Azure DevOps)
5. Configure the target:
   * For REST: Enter the destination URL
   * For GitHub/GitLab: Select repository and workflow details
6. Select the events to listen for
7. 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.

1. Open the create or update webhook form
2. In the "Test Webhook" section, select an event type
3. 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

1. Go to Settings → Webhooks
2. 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

1. Click the three-dot menu on the webhook row
2. Select "Update"
3. Modify the configuration
4. 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

1. Click the three-dot menu on the webhook row
2. Select "Delete"
3. Confirm the deletion

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

## Webhook payload

Webhook payloads include event details in JSON format.

### Payload structure

```json theme={null}
{
  "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

```javascript theme={null}
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');
});
```

<Note>
  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:

  ```javascript theme={null}
  app.use(express.json({
      verify: (req, res, buf) => {
          req.rawBody = buf.toString();
      }
  }));
  ```
</Note>

### Verification steps

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.