Webhooks

Webhooks let you trigger TinyOps rules from any external service that can send HTTP requests. Each rule gets a unique webhook URL that accepts POST requests with a JSON body. This makes TinyOps extensible to any tool in your stack, not just the built-in integrations.

How It Works

When you create a rule with a webhook trigger, TinyOps generates a unique endpoint URL for that rule. External services send POST requests to this URL, and the JSON body becomes available as trigger data within your rule’s conditions and action templates.

Endpoint Format


POST https://api.tinyops.cc/api/webhooks/rules/:ruleId

Replace :ruleId with your rule’s unique identifier, found on the rule detail page.

Authentication

Webhook requests are authenticated using a shared secret passed in the x-webhook-secret header:

webhook-request-example.yaml


method: POST
url: https://api.tinyops.cc/api/webhooks/rules/rule_abc123
headers:
  Content-Type: application/json
  x-webhook-secret: whsec_your_secret_here
body:
  event: deployment.completed
  service: api
  status: healthy

Keep your webhook secret secure. If compromised, rotate it immediately from the rule detail page. See the Secret Rotation section below.

Accessing Trigger Data

The JSON body of the webhook request is accessible in your rule using the trigger.data namespace:

Template Variable	Description
`{{trigger.data}}`	The full JSON body object
`{{trigger.data.fieldName}}`	A specific top-level field from the body
`{{trigger.data.nested.field}}`	Nested field access using dot notation

rule-using-webhook-data.yaml


name: custom-deploy-alert
trigger:
  type: webhook
condition:
  field: trigger.data.status
  operator: eq
  value: "failed"
action:
  type: notify
  channel: slack
  message: "Deployment failed for {{trigger.data.service}}: {{trigger.data.error}}"

Idempotency

To prevent duplicate processing, include the X-Delivery-Id header in your webhook requests. TinyOps deduplicates by the combination of ruleId and deliveryId. If the same delivery ID is sent twice for the same rule, the second request is ignored.

idempotent-request.yaml


headers:
  x-webhook-secret: whsec_your_secret_here
  X-Delivery-Id: delivery_unique_id_123

HMAC Verification

For additional security, you can enable HMAC signature verification on a per-rule basis. When enabled, TinyOps computes an HMAC-SHA256 signature of the request body and verifies it against the signature provided in the request.

Setting	Description
HMAC enabled	Toggle per rule from the rule detail page
Algorithm	HMAC-SHA256
Secret	Same webhook secret used for the `x-webhook-secret` header

Secret Rotation

You can rotate your webhook secret at any time from the rule detail page:

Navigate to the rule detail page

Click “Rotate Secret” in the webhook configuration section

Copy the new secret and update your external service

The old secret is invalidated immediately

After rotating a secret, the old secret stops working immediately. Make sure to update all services sending webhooks to this rule before or immediately after rotation.

Delivery Logs

TinyOps logs all incoming webhook deliveries for each rule. The delivery log includes:

Field	Description
Timestamp	When the request was received
Delivery ID	The `X-Delivery-Id` value (if provided)
Status	Whether the delivery was processed or deduplicated
Payload	The JSON body (redacted after 30 days)
Rule execution	Link to the resulting rule execution (if triggered)

Deploy Safety - uses webhooks for push event notifications
Schedules - alternative trigger type for time-based rules
Audit Log - tracks secret rotations and webhook configuration changes