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. Webhook-triggered actions must use exec: (not shell: or shellAfterCompleted).

config.yaml

actions:
  - title: Deploy Application
    id: deploy
    exec:
      - /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
    exec:
      - 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
    exec:
      - echo
      - "Processing request for {{ service }}"
    arguments:
      - name: service
        type: ascii
    execOnWebhook:
      - matchQuery:
          action: deploy
          env: production
        extract:
          service: "$.service"

A request to /webhooks?action=deploy&env=production with a JSON body containing "service" would match this action and pass that field into the service argument.

Match by JSON Body Path

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

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

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
    exec:
      - 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
    exec:
      - /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
    exec:
      - /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
    exec:
      - echo
      - 'Request ID: {{ index .Arguments "webhook_header_x-request-id" }}'
    arguments:
      - name: webhook_header_x-request-id
        type: ascii
    execOnWebhook:
      - matchHeaders:
          X-Event-Type: log

Header names that contain hyphens become argument keys with the same hyphens (for example webhook_header_x-request-id). Use the index map-lookup form shown above, because Go templates treat hyphens in bare identifiers as subtraction.

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
    exec:
      - /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