Webhooks API

The Webhooks API is the ingress endpoint that receives external event payloads and triggers rule execution. Unlike other API endpoints, webhooks do not use session authentication. Instead, they are secured with a per-rule webhook secret passed via header.

Base path: /api/webhooks

Endpoint

Parameters

Required headers

Request body

The body is a raw JSON payload. Its structure depends on the event source (GitHub, Slack, custom, etc.). TinyOps passes the entire payload to the rule for evaluation.

{
  "event": "push",
  "repository": "acme/api",
  "branch": "main",
  "author": "dev@acme.com",
  "commits": [
    { "id": "abc123", "message": "fix: resolve timeout" }
  ]
}

Idempotency

Include the X-Delivery-Id header with a unique identifier for each delivery. TinyOps uses this to deduplicate webhook deliveries. If the same delivery ID is received within a 5-minute window, the duplicate is acknowledged with a 200 response but not processed again.

X-Delivery-Id: d7e8f9a0-1234-5678-abcd-ef0123456789

HMAC Verification

When HMAC is enabled on a rule, TinyOps computes an HMAC-SHA256 signature of the request body using the webhook secret and includes it in the response for verification.

To verify incoming webhooks on your end, compute the HMAC yourself:

import crypto from 'crypto';
 
function verifySignature(body, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Response Codes

Example cURL

curl -X POST https://api.tinyops.cc/api/webhooks/rules/your-rule-id \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: whsec_abc123..." \
  -H "X-Delivery-Id: unique-id-here" \
  -d '{"event":"push","repository":"acme/api"}'