342 lines
8.2 KiB
Plaintext
342 lines
8.2 KiB
Plaintext
[#exec-webhook]
|
|
= 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`).
|
|
|
|
[source,yaml]
|
|
.`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
|
|
----
|
|
|
|
or
|
|
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:`:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
execOnWebhook:
|
|
- authType: none
|
|
matchHeaders:
|
|
X-Event-Type: my-event
|
|
----
|
|
|
|
=== HMAC-SHA256 Signature
|
|
|
|
Verify webhooks using HMAC-SHA256 signatures (commonly used by GitHub, GitLab, etc.):
|
|
|
|
[source,yaml]
|
|
----
|
|
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):
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
execOnWebhook:
|
|
- authType: basic
|
|
secret: "username:password"
|
|
matchHeaders:
|
|
X-Event-Type: deploy
|
|
----
|
|
|
|
Or with password only:
|
|
|
|
[source,yaml]
|
|
----
|
|
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:
|
|
|
|
[source,yaml]
|
|
----
|
|
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`:
|
|
|
|
[source,bash]
|
|
----
|
|
# 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
|
|
----
|
|
|
|
== See Also
|
|
|
|
* xref:action_execution/onwebhook_github.adoc[GitHub Webhooks] - Specific configuration for GitHub webhook events
|
|
* xref:solutions/on-git-push/index.adoc[GitOps Solution] - Running actions on Git push using hooks
|
|
* xref:api/start_action.adoc[Start Action API] - Alternative method for triggering actions via API
|