Proactive

Platform

Webhooks

Outbound HTTPS notifications for task, GitHub, report, integration, and security events. Configure endpoints in Access Control → Webhooks. Each delivery posts the stored event data (retries and the delivery detail view match what was sent). Task events include a task snapshot, project, and assignee; GitHub events include PR metadata and a linked task ref when available. Large text is omitted: task descriptions, GitHub review/comment bodies, diff hunks, and report content. Description-only task edits still emit task.updated with { "field": "description" } and no old or new value.

Delivery guarantees

  • Delivery is at-least-once. Receivers should dedupe on the event id.
  • Ordering is best-effort, not strict. Use createdAt /occurredAt when order matters.
  • Envelope shape: { id, type, apiVersion, createdAt, actor, data }. Current apiVersion is 2026-10-13.
  • Every delivery is an HTTP POST with a JSON body (application/json). Make sure your receiver accepts POST (n8n's Webhook node defaults to GET).
  • Request headers include X-Proactive-Event, X-Proactive-Event-Id, X-Proactive-Delivery-Id, X-Proactive-Timestamp, X-Proactive-Signature, and X-Proactive-Secret.

Verifying requests (no code)

Every delivery carries your endpoint's signing secret in the X-Proactive-Secret header. Configure your receiver to require that header with your secret as its value and reject anything else. Deliveries are HTTPS-only, so the header is encrypted in transit.

  1. In n8n: open the Webhook node, set HTTP Method to POST and Authentication to Header Auth.
  2. Create the credential with Name X-Proactive-Secret and Value set to your whsec_… secret.
  3. Requests without the correct header are rejected by n8n, so only Proactive (which knows the secret) can trigger the workflow.

The same works in any tool that supports a static header check. After rotating the secret, update the value in your receiver; the header always carries the newest secret.

Signature verification (optional)

Signatures are HMAC-SHA256 over {timestamp}.{rawBody}, encoded as v1=<hex>. During secret rotation, X-Proactive-Signature may contain multiple comma-separated values. Reject timestamps outside a 5-minute window.

Node.js

import crypto from "node:crypto";

function verifyProactiveSignature({
  secret,
  timestampHeader,
  signatureHeader,
  rawBody,
  toleranceSec = 300,
}) {
  const timestamp = Number(timestampHeader);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSec) return false;

  const expected =
    "v1=" +
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}.${rawBody}`, "utf8")
      .digest("hex");

  const candidates = String(signatureHeader)
    .split(",")
    .map((part) => part.trim());

  return candidates.some((value) => {
    const a = Buffer.from(value);
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

Python

import hashlib
import hmac
import time

def verify_proactive_signature(secret, timestamp_header, signature_header, raw_body, tolerance_sec=300):
    try:
        timestamp = int(timestamp_header)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - timestamp) > tolerance_sec:
        return False

    expected = "v1=" + hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.{raw_body}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    for candidate in signature_header.split(","):
        if hmac.compare_digest(candidate.strip(), expected):
            return True
    return False

Retry policy

  • Non-2xx responses (except HTTP 410) retry with exponential backoff and jitter: 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 12 hours.
  • After 7 attempts a delivery becomes DEAD. Dead deliveries can be manually resent from Access Control → Webhooks.
  • HTTP 410 disables the endpoint immediately. 10 consecutive dead deliveries also auto-disable it.
  • Retry-After is honoured when present, clamped to 24 hours. Delivery timeout is 10s; redirects are not followed.
  • Base backoff schedule (ms): [30000, 120000, 600000, 3600000, 21600000, 43200000].

Event catalog

Subscribe per endpoint. Personal events (reports, auth, integrations) always target the owning user. Project-scoped events fan out to active project members, optionally filtered by an allowlist.

Tasks

task.created

Task created — A task was created in a project you belong to. (project-scoped)

task.updated

Task updated — A task field changed (title, priority, due date, etc.). (project-scoped)

task.status_changed

Task status changed — A task moved between statuses. (project-scoped)

task.assigned

Task assigned — A task assignee was set or cleared. (project-scoped)

task.deleted

Task deleted — A task was soft-deleted. (project-scoped)

GitHub

github.pull_request.opened

Pull request opened — A linked GitHub pull request was opened. (installation-scoped)

github.pull_request.merged

Pull request merged — A linked GitHub pull request was merged. (installation-scoped)

github.pull_request.closed

Pull request closed — A linked GitHub pull request was closed without merging. (installation-scoped)

github.review.submitted

Review submitted — A pull request review was submitted. (installation-scoped)

github.review.requested

Review requested — A pull request review was requested. (installation-scoped)

github.comment.created

Comment created — A pull request or issue comment was created. (installation-scoped)

github.check_run.failed

Check run failed — A GitHub check run failed. (installation-scoped)

Reports

report.completed

Report completed — A report finished successfully. (user-scoped)

report.failed

Report failed — A report failed to generate. (user-scoped)

Failures

integration.github.sync_failed

GitHub sync failed — A GitHub sync job failed. (user-scoped)

integration.error

Integration error — An integration entered an error state. (user-scoped)

Security

auth.sign_in_denied

Sign-in denied — A sign-in attempt was denied. (user-scoped)

auth.unauthorized_request

Unauthorized request — An attributable unauthorized API or app request occurred. (user-scoped)

auth.api_token_created

API token created — An API token credential was created. (user-scoped)

auth.api_token_revoked

API token revoked — An API token credential was revoked. (user-scoped)

integration.connected

Integration connected — An integration was connected. (user-scoped)

integration.disconnected

Integration disconnected — An integration was disconnected. (user-scoped)

admin.action_denied

Admin action denied — An admin action was denied. (user-scoped)