Webhooks

Outbound webhooks let you route Roboticks events into anything that accepts HTTP — internal dashboards, ticketing systems, data warehouses, custom Slack apps your security team has standardised on, or your own tooling.

Set up

Add a webhook

Settings → Integrations → Webhooks → Add. Paste your endpoint URL (HTTPS only). Pick a name.

Generate a signing secret

Roboticks generates a 32-byte secret. Copy it once — it’s never shown in plaintext again. Store it where your receiver can read it.

Pick events

Toggle which event types route here. Defaults: all test_run.* and evidence_pack.* events.

Send a test

Hit Send test event. The endpoint receives a synthetic test_run.completed payload.

Payload envelope

Every webhook delivery has the same envelope:

{
  "id": "evt_7c2f...",
  "type": "test_run.completed",
  "occurred_at": "2026-05-24T12:44:15.221Z",
  "org": { "id": 42, "slug": "acme" },
  "project": { "id": 18, "slug": "warehouse" },
  "data": { /* event-type-specific payload, see below */ },
  "links": {
    "dashboard": "https://app.roboticks.io/r/warehouse/runs/8a1f3c2d"
  }
}

Event types

`test_run.completed`

"data": {
  "run_id": "8a1f3c2d-...",
  "status": "failed",
  "git": { "sha": "abcdef123456", "ref": "refs/heads/main", "pr_number": 214 },
  "pool": { "name": "prod-gpu-farm", "type": "self-hosted" },
  "tests": { "total": 412, "passed": 411, "failed": 1, "skipped": 0 },
  "duration_seconds": 139,
  "failures": [{
    "id": "tests/test_estop.py::test_estop_halts_motion",
    "message": "stop reached at 142ms (budget 100ms)",
    "requirements": ["REQ-001"]
  }],
  "requirement_coverage": {
    "confirmed": 142,
    "uncovered": 18,
    "total": 160,
    "delta_vs_previous": { "confirmed": -1, "uncovered": 1, "stale": 0 }
  }
}

`requirement.gap_opened`

"data": {
  "requirement_id": "REQ-051",
  "title": "Tool-change interlock",
  "type": "safety",
  "previously_confirmed_by": "tests/test_toolchange.py::test_interlock",
  "last_confirmed_run_id": "8a1a72e0-...",
  "last_confirmed_at": "2026-05-21T17:30:00Z",
  "reason": "test_deleted",
  "responsible_commit": { "sha": "abcdef123456", "author": "amir@roboticks.io" }
}

reason is one of: test_deleted, test_renamed, test_failing, requirement_added, staleness_window_exceeded.

`evidence_pack.generated`

"data": {
  "pack_id": "ev_a1b2...",
  "release_tag": "v2.4.0",
  "size_bytes": 4423012,
  "formats": ["pdf", "reqif", "zip"],
  "hash_chain_entries": 142,
  "signature": {
    "algorithm": "cosign",
    "key_id": "rbtk-prod-2026"
  },
  "download_urls": {
    "pdf":   "https://api.roboticks.io/v1/evidence-packs/ev_a1b2/pdf",
    "reqif": "https://api.roboticks.io/v1/evidence-packs/ev_a1b2/reqif",
    "zip":   "https://api.roboticks.io/v1/evidence-packs/ev_a1b2/zip"
  }
}

`standard.amendment_published`

"data": {
  "standard": "iso-10218-2-2025",
  "amendment": "A1",
  "published_at": "2026-04-12",
  "summary": "Revised §5.7.5 protective-stop performance criteria",
  "impacted_pinned_requirements": ["REQ-001", "REQ-009", "REQ-049"],
  "change_impact_report_url": "https://api.roboticks.io/v1/standards/iso-10218-2-2025/A1/impact"
}

`runner_pool.offline`

"data": {
  "pool_name": "onprem-airgapped",
  "pool_type": "self-hosted",
  "airgapped": true,
  "last_online_at": "2026-05-24T11:27:01Z",
  "queued_jobs": 14
}

Signatures

Every delivery includes an HMAC-SHA256 signature in the X-Roboticks-Signature header:

X-Roboticks-Signature: t=1716561855,v1=abc123...

t is the Unix timestamp the signature was minted (use to defeat replay); v1 is the HMAC.

Verify

Compute HMAC-SHA256 over "{t}.{raw_body}" with your signing secret. Compare to v1 in constant time.

Python
Node.js
Go

import hmac, hashlib, time

def verify(raw_body: bytes, sig_header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in sig_header.split(","))
    t = int(parts["t"])
    if abs(time.time() - t) > tolerance:
        return False  # outside replay window
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

const crypto = require('crypto');

function verify(rawBody, sigHeader, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    sigHeader.split(',').map(p => p.split('=', 2))
  );
  const t = parseInt(parts.t, 10);
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const signed = Buffer.concat([Buffer.from(`${t}.`), rawBody]);
  const expected = crypto.createHmac('sha256', secret).update(signed).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "strings"
  "strconv"
  "time"
)

func Verify(rawBody []byte, sigHeader, secret string, toleranceSec int64) bool {
  parts := map[string]string{}
  for _, p := range strings.Split(sigHeader, ",") {
    kv := strings.SplitN(p, "=", 2)
    parts[kv[0]] = kv[1]
  }
  t, _ := strconv.ParseInt(parts["t"], 10, 64)
  if abs(time.Now().Unix()-t) > toleranceSec { return false }
  mac := hmac.New(sha256.New, []byte(secret))
  mac.Write([]byte(strconv.FormatInt(t, 10) + "."))
  mac.Write(rawBody)
  expected := hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(expected), []byte(parts["v1"]))
}

Always reject deliveries outside the 5-minute timestamp tolerance to defeat replay attacks.

Retry semantics

Failed deliveries (non-2xx response, timeout > 10 s, connection error) retry with exponential backoff:

Attempt	Delay
1	immediate
2	30 s
3	5 min
4	30 min
5	4 h
6	24 h

After 6 failed attempts, the delivery is marked failed and a webhook.delivery_failed event fires (you can wire that to Slack to know you’re losing data). Replays from the dashboard: Settings → Integrations → Webhooks → Delivery log → ⋯ → Resend.

Idempotency

Use the envelope id for idempotency. The same event will never appear under two different id values; the same id may appear more than once if your endpoint timed out and we retried.

INSERT INTO webhook_events (id, type, occurred_at, payload)
VALUES ($1, $2, $3, $4)
ON CONFLICT (id) DO NOTHING;

Best practice

Acknowledge fast: return 2xx within 5 s, then process async. Don’t do heavy work in the request handler.
Verify the signature before parsing JSON.
Log the envelope id for every delivery; correlate with the delivery log on triage.
Reject deliveries whose org.id doesn’t match your expectation (defence-in-depth).

Troubleshooting

Deliveries always retried then failed

Most often the endpoint takes > 10 s to respond. Move processing to a queue and ack immediately.

Signature verification fails for some events

You’re parsing JSON before computing the HMAC. Compute the HMAC over the raw bytes of the request body — even whitespace differences invalidate the signature.

Want to inspect raw deliveries

Use webhook.site or ngrok http 4000 for local development. Both surface the exact headers and body Roboticks sends.

Quick Start

GitHub App

Requirements

Traceability

Testing

SDK

Self-Hosted Runners

AI Features

CLI

Evidence Packs

Standards Coverage

Compliance Patterns

Integrations

Pricing

Resources

Webhooks

Webhooks

Set up

Payload envelope

Event types

`test_run.completed`

`requirement.gap_opened`

`evidence_pack.generated`

`standard.amendment_published`

`runner_pool.offline`

Signatures

Verify

Retry semantics

Idempotency

Best practice

Troubleshooting

​Webhooks

​Set up

​Payload envelope

​Event types

​test_run.completed

​requirement.gap_opened

​evidence_pack.generated

​standard.amendment_published

​runner_pool.offline

​Signatures

​Verify

​Retry semantics

​Idempotency

​Best practice

​Troubleshooting

Webhooks

Set up

Payload envelope

Event types

`test_run.completed`

`requirement.gap_opened`

`evidence_pack.generated`

`standard.amendment_published`

`runner_pool.offline`

Signatures

Verify

Retry semantics

Idempotency

Best practice

Troubleshooting