Skip to content
CodeCleared Docs
AppFrançais
Published

Last reviewed: 2026-07-25

Outbound webhooks

Securely deliver CodeCleared scan, policy, score, and finding events to your HTTPS receiver with signatures, retries, and idempotency.

Purpose

Webhooks deliver selected scan, policy, score, pull-request-check, and finding lifecycle events to your HTTPS receiver. Configure endpoints in Settings → Webhooks and store each endpoint secret in a dedicated secret manager.

Prerequisites

Webhooks are typically available on Team and above. Your receiver must accept HTTPS requests, preserve the raw request body, return a successful response promptly, and be able to deduplicate deliveries.

Steps

  1. Add an HTTPS endpoint and select only the events your process needs.
  2. Save its endpoint secret outside source control.
  3. Send a test delivery and inspect your receiver logs without retaining payload secrets.
  4. Verify the signature before parsing or acting on the event.
import crypto from 'node:crypto';

export function verifyWebhook(rawBody, signature, secret, now = Math.floor(Date.now() / 1000)) {
  const fields = Object.fromEntries(signature.split(',').map(part => part.split('=')));
  const timestamp = Number(fields.t);
  if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return fields.v1 && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(fields.v1));
}

Business rules

Headers are X-CodeCleared-Event, X-CodeCleared-Delivery, and X-CodeCleared-Signature. The signature is t=unix,v1=hex: HMAC-SHA256 over ${t}.${rawBody}. Reject timestamps outside roughly 300 seconds and use delivery ID as an idempotency key. Customer-visible events include scan.completed, compliance_score.changed, policy and PR-check violations, and finding SLA/governance lifecycle events.

Scenarios & edge cases

Duplicate delivery: acknowledge safely after your idempotency check. Signature mismatch: use the untouched raw body and the correct endpoint secret; JSON reformatting changes the signed input. Old delivery: reject it rather than extending the timestamp tolerance. Endpoint migration: add and test a new endpoint before removing the old one.

Limits

An organization can configure about 10 endpoints and view about 100 delivery-history entries. Limits are product limits; do not use endpoint URLs for credentials. For native Jira/Linear ticket creation without building a receiver, see Issue trackers.

Common errors

  • Parsing then reserializing the body before verification.
  • Comparing signatures with a normal string comparison.
  • Ignoring X-CodeCleared-Delivery and creating duplicate tickets.
  • Treating a failed delivery as permission to skip verification.

Links