Skip to content

Webhooks ​

ordyn-webhooks lets external systems trigger endpoint jobs and infrastructure jobs through HTTP webhooks.

The webhook service receives public HTTP requests, authenticates them according to each webhook definition, and makes normalized request data available to the triggered job.

Use webhooks when another application should start an Ordyn job, for example:

  • a monitoring system detects a condition and asks Ordyn to remediate the affected machine
  • a CI or deployment platform starts an infrastructure build or administration job
  • a company portal starts a controlled endpoint action without giving the caller direct Ordyn server access
  • another automation tool passes structured data into an Ordyn job

Webhooks are available in Administration > Services on the Webhooks tab.

Setup ​

Create a webhook service client and enroll the service using the installation instructions below. Then create a webhook definition, connect it to a job automation, and give its URL and authentication details to the calling system.

Callers need access to the webhook service's public HTTPS address. The service needs outbound access to Edge.

Service clients ​

Under Administration > Services > Webhooks, create a client with its assigned Edge service and public base URL, such as https://ordyn-webhooks.example.com. Copy its service client ID and issue a matching enrollment token.

Preserve the service's data volume during upgrades. Plan certificate renewal before its displayed expiration.

Runtime configuration ​

The installation example below sets the required host, client ID, and public URL. Set ORDYN_WEBHOOK_BODY_LIMIT if you need to change the maximum request size.

On the Ordyn server, ORDYN_WEBHOOK_EVENT_RETENTION_DAYS controls event retention. It defaults to 30 days; zero or a negative value disables pruning.

Installation ​

Prerequisites:

Checkout the webhook deployment folder from the Ordyn compose repository:

bash
if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add webhooks

Create the environment file:

bash
cd /opt/ordyn-compose/webhooks
cp .env.example .env

Set these values in .env:

dotenv
SERVICE_DOMAIN=ordyn-webhooks.example.com
ORDYN_WEBHOOK_EDGE_HOST=ordyn-edge.example.com
ORDYN_WEBHOOK_SERVICE_CLIENT_ID=<service-client-id>
ORDYN_WEBHOOK_PUBLIC_BASE_URL=https://ordyn-webhooks.example.com

Pull and verify the service image:

bash
docker compose pull
python3 /opt/cosign-docker-verify/verify.py

Continue only when the webhook image verifies successfully and no failed verification message appears. Issue a service-client enrollment token for the webhook service client in Ordyn, stop any running service container, and enroll the persistent service state:

bash
docker compose stop webhooks
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps webhooks npm run enroll -- --token-stdin

After enrollment succeeds, start the service:

bash
docker compose up -d webhooks

To renew, recover, or replace its service-client certificate, issue a new token and run forced enrollment while the service is stopped:

bash
docker compose stop webhooks
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps webhooks npm run enroll -- --token-stdin --force

Run docker compose up -d webhooks only after forced enrollment succeeds. Do not use docker compose exec for enrollment.

The webhook service needs public HTTPS ingress for /v1/hooks/. The provided compose file routes that path through Traefik.

Public ingress ​

The service exposes incoming webhook calls at:

text
/v1/hooks/:slug

The slug is generated by Ordyn when the webhook is created. It is part of the copied webhook URL.

Only that ingress path needs to be publicly reachable. Service-client enrollment and control traffic are outbound from the webhook service to edge.

Source-IP authentication uses caller addresses forwarded by Traefik.

Configure rate limiting on public webhook routes when a webhook endpoint is exposed to untrusted networks or high-volume callers.

Webhook definitions ​

Create a definition on the Webhooks page and choose its service client, scope, allowed HTTP methods, and authentication.

An endpoint-scoped webhook is bound to one approved endpoint. An infrastructure-scoped webhook starts infrastructure job automations without endpoint targets. The incoming request cannot choose a target, job, or Runner.

Remove automation and Git repository references before changing the scope or endpoint, or deleting the definition. Disable a webhook to stop accepting calls.

Allowed methods ​

Allow the methods used by the integration. The default is POST; GET, PUT, PATCH, and DELETE are also supported.

Authentication ​

Webhook authentication is configured per webhook definition.

Supported modes:

ModeBehavior
UnauthenticatedNo token is required. Use only for trusted networks or low-risk integrations.
Bearer tokenThe caller sends Authorization: Bearer <token>.
Header tokenThe caller sends the token in the configured header, for example X-Ordyn-Webhook-Token.
Source IP allowlistThe caller source IP must match one configured IP address or CIDR range.

Copy bearer or header tokens when configuring the integration; they are not shown again after saving.

Source IP allowlists support individual IP addresses and CIDR ranges, for example:

text
203.0.113.10
203.0.113.0/24
2001:db8::/32

Source-IP checks use the caller address forwarded by Traefik.

Request payloads ​

Jobs can use the request's method, source IP, headers, query parameters, and body. JSON and form-encoded bodies are available as structured fields; other bodies are text. Authentication tokens should not be used as job inputs.

Connect Webhooks To Jobs ​

Endpoint Jobs ​

Add a Webhook received event automation for the webhook's endpoint and choose the job to run. Select the webhook definition and, if needed, a random delay to spread repeated requests.

Infrastructure Jobs ​

On an infrastructure job's Automations page, add a Webhook received automation and select an infrastructure-scoped webhook. The job runs once using its configured Runner pool.

The job must be enabled and within its allowed start window when the request is processed. See Automations for scheduling and trigger behavior.

To use a webhook to accelerate Git change detection, select it on the repository under Administration → Services → Git and add a Git changes automation to the job. See Git sources.

Filter requests ​

Add Conditions to a Webhook received automation to choose which incoming requests start its job. Each automation has its own conditions, so several jobs can share a webhook and respond to different requests. Leave conditions empty to accept every request accepted by the webhook.

Use the Guided builder to compare request fields and combine conditions with All or Any, or use Advanced expression to write a condition directly. Request data is available under trigger.webhook, such as trigger.webhook.body and trigger.webhook.headers. Header names are lowercase. Conditions can use incoming request data, but not job variables or task results.

Only conditions that evaluate to true start the job. Missing request fields resolve to null. A Filtered out result in the webhook list means the request did not match the automation's conditions.

Build Gitea pull requests ​

Configure a Git source for the Gitea repository. Include +:refs/(pull/*) in its branch specification and set the job's branch filter to +:pull/* for PR builds.

Create an infrastructure-scoped webhook with bearer-token authentication and select it on the Git repository entry. Add a Git changes automation to the job. In Gitea, add a repository webhook with the Ordyn webhook URL, POST, application/json, and Authorization Header set to Bearer <token>. Subscribe to pull-request creation and synchronization events. See Gitea webhook configuration.

Gitea exposes pull requests as refs/pull/<number>/head. Each delivery prompts a repository check; the job's Git changes automation determines which refs to build.

Job variables ​

Triggered jobs receive webhook trigger details under:

text
trigger.webhook

The run also has trigger.type set to webhook_received and trigger.source set to webhook. See Variables for the full trigger field list.

Webhook definitions can also map selected request values to short job variables under:

text
webhook.<name>

For example, a mapping with:

NamePath
build_idbody.build.id

makes the value available as:

text
{{ webhook.build_id }}

Mapping paths refer to request data. Use these prefixes:

  • body
  • query
  • headers
  • source_ip
  • method
  • content_type

Use mappings for values that job authors should consume directly. Use trigger.webhook.* when a job needs the full request context.

Example ​

An external system sends:

bash
curl -X POST \
  https://ordyn-webhooks.example.com/v1/hooks/3d72... \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  --data '{"build":{"id":"2026.06.25.1"},"action":"restart-service"}'

With a variable mapping:

NamePath
build_idbody.build.id
actionbody.action

the triggered job can use:

text
{{ webhook.build_id }}
{{ webhook.action }}
{{ trigger.webhook.source_ip }}

Events and diagnostics ​

Review webhook events to check whether a request arrived and which automation it started. If no job starts, check the webhook's scope, endpoint approval, matching automations, and job validity window. Events are retained for 30 days by default.

Support bundles ​

For enrollment, connectivity, or authentication failures, include the webhook service client in a service-client log bundle.

Security recommendations ​

Use HTTPS and token authentication or a source-IP allowlist. Create a separate webhook for each integration purpose and limit its automations to the intended work. Map only the request values the job needs, and avoid putting secrets in request bodies.

Limitations ​

Webhooks parse JSON and form data but do not transform arbitrary payload formats. Use variable mappings to provide stable inputs to job authors.