Execute on webhook

Webhooks allow external services to trigger OliveTin actions by sending HTTP POST requests. This is useful for integrating OliveTin with CI/CD pipelines, monitoring systems, IoT devices, or any service that can send HTTP requests.

OliveTin provides a dedicated webhook endpoint at /webhooks that can receive webhook payloads and match them to configured actions.

Basic Configuration

To configure an action to run on a webhook, add the execOnWebhook property to your action:

config.yaml

actions:
  - title: Deploy Application
    id: deploy
    shell: /opt/scripts/deploy.sh
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: deploy

This action will be triggered when a POST request is sent to /webhooks with the header X-Event-Type: deploy.

Webhook Endpoint

All webhooks are received at:

http://your-olivetin-server:1337/webhooks

http://your-olivetin-server:1337/webhooks/

Both paths work identically. All webhook requests must use the HTTP POST method.

Matching Webhooks

OliveTin can match incoming webhooks based on several criteria:

Match by Headers

Match webhooks based on HTTP header values:

actions:
  - title: Process Event
    shell: echo "Processing event"
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: my-event
          X-Source: my-service

All specified headers must match for the webhook to trigger the action.

Match by Query Parameters

Match webhooks based on URL query parameters:

actions:
  - title: Process Request
    shell: echo "Processing request for {{ service }}"
    arguments:
      - name: service
        type: ascii
    execOnWebhook:
      - matchQuery:
          action: deploy
          env: production

A request to /webhooks?action=deploy&env=production would match this action.

Match by JSON Body Path

Match webhooks based on values in the JSON request body using JSONPath expressions:

actions:
  - title: Handle Push Event
    shell: echo "Push to {{ branch }}"
    arguments:
      - name: branch
        type: ascii
    execOnWebhook:
      - matchPath: "$.event_type=push"

The matchPath format is jsonpath=value. You can also just specify a JSONPath without a value to match if the path exists:

execOnWebhook:
  - matchPath: "$.repository.name"  # Matches if this path exists in the JSON

Using Regex for Matching

Header and query parameter values can use regex patterns by prefixing with regex::

actions:
  - title: Handle Multiple Events
    shell: echo "Handling event"
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: "regex:^(push|pull_request|release)$"

Combining Match Criteria

You can combine multiple match criteria. All criteria must match for the webhook to trigger:

actions:
  - title: Production Deploy
    shell: /opt/scripts/deploy.sh production
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: deploy
        matchQuery:
          environment: production
        matchPath: "$.status=approved"

Extracting Arguments from Webhooks

You can extract values from the webhook payload and pass them as arguments to your action using JSONPath expressions:

actions:
  - title: Deploy Version
    shell: |
      echo "Deploying version {{ version }} to {{ environment }}"
      /opt/scripts/deploy.sh "{{ version }}" "{{ environment }}"
    arguments:
      - name: version
        type: ascii
      - name: environment
        type: ascii
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: deploy
        extract:
          version: "$.release.tag_name"
          environment: "$.target.environment"

The extract map defines which action arguments to populate from the webhook payload. The key is the argument name, and the value is the JSONPath expression to extract the value.

Automatic Webhook Metadata

OliveTin automatically adds several metadata arguments from each webhook request:

webhook_method - The HTTP method (always POST for webhooks)
webhook_path - The request URL path
webhook_query - The raw query string
webhook_header_<name> - Each HTTP header (lowercase name)

For example, to access the X-Request-Id header in your action:

actions:
  - title: Log Request
    shell: echo "Request ID: {{ webhook_header_x-request-id }}"
    arguments:
      - name: webhook_header_x-request-id
        type: ascii
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: log

Webhook Authentication

OliveTin supports several authentication methods to verify webhook requests:

No Authentication

By default, webhooks have no authentication. Any request matching the criteria will trigger the action:

execOnWebhook:
  - authType: none
    matchHeaders:
      X-Event-Type: my-event

HMAC-SHA256 Signature

Verify webhooks using HMAC-SHA256 signatures (commonly used by GitHub, GitLab, etc.):

execOnWebhook:
  - authType: hmac-sha256
    authHeader: X-Hub-Signature-256
    secret: your-webhook-secret
    matchHeaders:
      X-Event-Type: push

The authHeader specifies which header contains the signature. The signature should be in the format sha256=<hex-encoded-signature>.

HMAC-SHA1 Signature

For services using HMAC-SHA1 (legacy GitHub webhooks):

execOnWebhook:
  - authType: hmac-sha1
    authHeader: X-Hub-Signature
    secret: your-webhook-secret
    matchHeaders:
      X-Event-Type: push

Bearer Token

Verify webhooks using a Bearer token in the Authorization header:

execOnWebhook:
  - authType: bearer
    secret: your-bearer-token
    matchHeaders:
      X-Event-Type: deploy

The webhook sender must include Authorization: Bearer your-bearer-token in the request.

Basic Authentication

Verify webhooks using HTTP Basic authentication:

execOnWebhook:
  - authType: basic
    secret: "username:password"
    matchHeaders:
      X-Event-Type: deploy

Or with password only:

execOnWebhook:
  - authType: basic
    secret: "mypassword"
    matchHeaders:
      X-Event-Type: deploy

Multiple Webhook Triggers

An action can have multiple webhook configurations. The action will be triggered if any of them match:

actions:
  - title: Deploy
    shell: /opt/scripts/deploy.sh
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: deploy-manual
      - matchHeaders:
          X-Event-Type: deploy-auto
        matchPath: "$.status=success"

Testing Webhooks

You can test your webhook configuration using curl:

# Simple webhook with headers
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Event-Type: deploy" \
  -d '{"version": "1.2.3"}' \
  http://localhost:1337/webhooks

# Webhook with HMAC-SHA256 authentication
SECRET="your-secret"
PAYLOAD='{"event": "push", "branch": "main"}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Event-Type: push" \
  -H "X-Hub-Signature-256: sha256=$SIGNATURE" \
  -d "$PAYLOAD" \
  http://localhost:1337/webhooks