Webhooks Overview

Set up webhooks to automatically trigger pipelines from Git events.

Webhooks

Webhooks enable automatic pipeline triggers when events occur in your Git repository.

How It Works

1. You configure a webhook in your Git provider (GitHub, GitLab, etc.)
2. When an event occurs (push, PR, etc.), your Git provider sends a POST request to Sluice
3. Sluice validates the request signature
4. If valid, Sluice triggers the appropriate pipeline
5. The pipeline runs with Git context (branch, commit, etc.)

Getting Your Webhook URL

Each pipeline has a unique webhook URL:

1. Navigate to your pipeline in the dashboard
2. Go to the Settings tab
3. Find the Webhooks section
4. Copy the Webhook URL

The URL format is:

https://api.sluice.dev/webhooks/pipelines/{pipeline_id}

Webhook Secret

For security, webhooks should be signed. Sluice provides a secret for each pipeline:

1. In the Webhooks section, find the Secret
2. Click Show or Copy to get the secret
3. Configure this secret in your Git provider

Supported Events

Event Filtering

Configure which events trigger your pipeline:

webhooks:
  events:
    - push
    - pull_request
  branches:
    include:
      - main
      - develop
      - 'feature/*'
    exclude:
      - 'dependabot/*'

Branch Patterns

Use glob patterns to match branches:

Git Context

When triggered by webhook, these variables are available:

For pull requests:

Security

Signature Verification

Sluice verifies all incoming webhooks using the configured secret:

• GitHub: X-Hub-Signature-256 header with HMAC-SHA256
• GitLab: X-Gitlab-Token header with secret token

Requests with invalid or missing signatures are rejected.

IP Allowlisting

For additional security, you can restrict webhooks to specific IP ranges:

webhooks:
  allowedIPs:
    - 140.82.112.0/20 # GitHub
    - 192.30.252.0/22 # GitHub

Retry Behavior

If webhook processing fails, Sluice does not retry automatically. Check your Git provider’s webhook delivery logs for:

• Response status codes
• Response body (error messages)
• Delivery timing

Testing Webhooks

Manual Test

Most Git providers let you redeliver webhooks:

1. Go to your repository settings
2. Find the webhook configuration
3. View recent deliveries
4. Click “Redeliver” on any event

Local Testing

For local development, use a tunnel service:

# Using ngrok
ngrok http 8080

# Configure the ngrok URL as your webhook endpoint

Troubleshooting

Next Steps

• GitHub Setup - Configure GitHub webhooks
• GitLab Setup - Configure GitLab webhooks