Skip to content
Docs

Trigger automation from outside

A signed incoming webhook lets a system outside Orbit, such as a deployment script, start one of your automation rules. This page is for project administrators who set the webhook up and for developers who send the request. In development

The rule format, triggers and smart values are on the Automation rules page. This page covers the sending side.

Set up the webhook

Section titled “Set up the webhook”
  1. Create a rule whose trigger is webhook.received, and publish it. A rule with another trigger answers 409 automation_not_webhook.
  2. As a project administrator, create the rule’s webhook with POST /automations/{id}/webhook. The answer is 201 with path, url, createdAt and a secret that starts with owhs_.
  3. Copy the secret now. Orbit shows it once. Creating a new secret stops the old one.

GET /automations/{id}/webhook tells you whether the webhook is configured, its path and url, and when it last received a request. DELETE removes it.

The webhook of a rule belongs to its own project. A rule that applies to every project of the site cannot be a webhook rule. A copied or imported rule needs its webhook set up again, because the secret is never exported. Orbit stores the secret apart from the rule, its history, its exports and its events.

Send a request

Section titled “Send a request”

Post to the rule’s url, which has the form https://acme.orbit.inortix.com/api/v1/automation-webhooks/<rule id>. No sign-in is needed, only the signature.

Part Rules
Orbit-Signature header t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret>. Up to four v1 values.
Body JSON, at most 64 KiB
issues Optional. Up to 100 work item keys or ids from the rule’s project. The rule runs on these work items only.
data Optional. Any JSON, available to the rule as {{webhook.<path>}}, with list indexes such as {{webhook.items.0.id}}
Request body
{
  "issues": ["ORB-12", "ORB-13"],
  "data": { "deploy": { "id": "d-4512", "result": "ok" } }
}

The request runs the published rule at once, as the rule’s actor. Sign the exact bytes that you send.

Call it from a Forge pipeline

Section titled “Call it from a Forge pipeline”

Store the webhook URL and secret as masked CI variables, then call the webhook after a deployment.

.gitlab-ci.yml
notify_orbit:
  stage: .post
  script:
    - |
      body='{"issues":["ORB-12"],"data":{"deploy":{"result":"ok"}}}'
      t=$(date +%s)
      sig=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$ORBIT_WEBHOOK_SECRET" -hex | sed 's/^.* //')
      curl -fsS -X POST "$ORBIT_WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -H "Orbit-Signature: t=$t,v1=$sig" \
        --data "$body"

Jobs have no network by default. Use a runner that is configured with a job network, see Runners.

Read the answer

Section titled “Read the answer”

A successful request answers with the run.

Field Meaning
status The status of the run
runId, ruleVersion The run and the published version of the rule that ran
matched, changed How many work items matched and how many the rule changed
unknownIssues Entries of issues that Orbit did not find
error, reason Present when the run failed or was skipped

Errors use these codes.

HTTP status Code Meaning
401 webhook_signature_invalid The signature is missing, malformed or wrong
401 webhook_signature_expired The t value is more than five minutes off
400 webhook_body_invalid The body is not the expected JSON
404 none The rule is unknown or has no secret
409 automation_disabled, automation_not_webhook, automation_actor_unavailable The rule is off, has another trigger, or its actor is unavailable
413 none The body is over 64 KiB
503 automation_retry_pending A run for the same delivery is waiting to retry. Wait for Retry-After, 5 seconds.

Sending the same signed request again returns the first run’s answer instead of running the rule twice.

Section titled “Related”