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/occurredAtwhen order matters. - Envelope shape:
{ id, type, apiVersion, createdAt, actor, data }. CurrentapiVersionis2026-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, andX-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.
- In n8n: open the Webhook node, set HTTP Method to
POSTand Authentication toHeader Auth. - Create the credential with Name
X-Proactive-Secretand Value set to yourwhsec_…secret. - 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 FalseRetry 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-Afteris 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)