Nullgap.dev Docs

Integrations

Outbound webhooks

Receive a signed JSON event at your own HTTPS endpoint when a review, a pentest or a fix run finishes or a finding changes, and verify that it came from Nullgap.

An outbound webhook is an HTTPS address of yours that Nullgap posts a signed JSON event to when something happens in your organisation. Use it to open tickets, page someone, update a dashboard or start a pipeline.

#Add an endpoint

You need to be an admin or owner, signed in to the console. An API key cannot add an endpoint or rotate its secret: where findings are sent is a setting a person has to confirm, and if your account has multi-factor sign-in you are asked for a fresh code.

  1. Open Integrations and find the Webhooks card. Choose Add webhook.
  2. Enter the Endpoint address and tick the events you want. All are ticked to begin with.
  3. Choose Add webhook. The Signing secret is shown once. Copy it into your secret store before closing the dialog.

Rules for the address:

RuleDetail
Schemehttps only.
HostA public address. Private, loopback and link-local addresses are refused, both by name and by what the name resolves to at each delivery.
FormNo user name or password in the URL, no fragment, at most 500 characters.
LimitsUp to 10 endpoints per organisation. The same address cannot be added twice.

An admin API key can do everything else: list endpoints, change the events, switch an endpoint off and on, send a test event and remove an endpoint.

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks"
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":["finding.created","finding.state_changed"],"enabled":true}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/wh_123"

The full list of routes is in the outbound webhooks reference.

#Events

EventSent when
review.completedA pull request review finished, whether or not it reported anything.
review.failedA review stopped with an error. A review that was skipped or cancelled sends nothing.
pentest.startedA pentest was accepted and queued: started in the console, through the API, from Slack, as a retest or by a schedule.
pentest.completedA pentest or retest finished.
pentest.failedA pentest stopped with an error. A cancelled pentest sends nothing.
remediation.completedA fix run finished, with any outcome. A fix run that is stopped by an error or cancelled sends nothing.
finding.createdA finding was recorded for the first time by a review or pentest, once per finding, or a finding that had been held back by an earlier decision was brought back.
finding.state_changedSomeone changed a finding's state: in the console, through the API, in bulk, by a command on the pull request, from Slack, or by closing or reopening its Jira issue.
finding.expert_reviewedA Nullgap security researcher decided on a finding: an expert review you asked for, or researcher validation under contract.
pingSomeone pressed Send test. Not selectable; see the test event.

#The envelope

Every event has the same outer shape. The request is a POST with content-type: application/json and user-agent: Nullgap-Webhooks/1.

{
  "id": "evt_5f0c2a9b1d3e",
  "type": "finding.created",
  "createdAt": "2026-11-16T09:30:00.000Z",
  "organisation": "acme",
  "data": {}
}
FieldMeaning
idThe event id. The same on every retry and equal to the webhook-id header. Each endpoint gets its own id for the same occurrence.
typeOne of the events above.
createdAtWhen the event was recorded, not when this attempt was sent.
organisationYour organisation's slug.
dataDepends on type; see below.

#A finding in an event

Wherever an event carries a finding it has this shape:

{
  "id": "fnd_3b1f09c2a7d4",
  "title": "SQL injection in order lookup",
  "severity": "high",
  "assurance": "proven",
  "cwe": ["CWE-89"],
  "file": "src/orders.js",
  "line": 42,
  "state": "open",
  "url": "https://nullgap.example/acme/findings/fnd_3b1f09c2a7d4"
}
FieldValues
severitycritical, high, medium, low, info
assuranceThe finding's verification status: proven (a probe reproduced it), fixed (proven, and a fix has passed verification), verified (an independent check agreed), candidate (not confirmed) or rejected (a check called it a false positive). In terms of the three assurance levels, proven and fixed are proven, verified is verified, and the other two are unverified.
cweA list of weakness ids, possibly empty.
file, lineWhere the finding is, or null when it has no code location.
stateopen, patched, accepted_risk, false_positive
urlThe finding in the console.

#Data by event

review.completed: findings lists what this review reported, new or seen again.

{
  "review": {
    "id": "rev_8a2d4c6e0f1b",
    "repository": "acme/shop",
    "pullRequest": 7,
    "headSha": "9f2c1e7a...",
    "status": "completed",
    "checkConclusion": "failure",
    "url": "https://nullgap.example/acme/reviews/rev_8a2d4c6e0f1b"
  },
  "findings": []
}

checkConclusion is success, failure, neutral or null.

review.failed:

{
  "review": { "id": "rev_8a2d4c6e0f1b", "repository": "acme/shop", "pullRequest": 7, "status": "failed", "error": "...", "url": "..." }
}

pentest.started: startedBy is the person's e-mail address, api-key:<key name> or schedule. retestOf is the id of the pentest being retested, or null.

{
  "pentest": {
    "id": "pen_1c3e5a7b9d0f",
    "repository": "acme/shop",
    "ref": "main",
    "status": "queued",
    "linesOfCode": 48210,
    "startedBy": "dana@acme.example",
    "retestOf": null,
    "url": "https://nullgap.example/acme/pentests/pen_1c3e5a7b9d0f"
  }
}

pentest.completed: findings lists what this pentest reported.

{
  "pentest": { "id": "pen_1c3e5a7b9d0f", "repository": "acme/shop", "ref": "main", "status": "completed", "linesOfCode": 48210, "url": "..." },
  "findings": []
}

pentest.failed:

{
  "pentest": { "id": "pen_1c3e5a7b9d0f", "repository": "acme/shop", "ref": "main", "status": "failed", "error": "...", "url": "..." }
}

remediation.completed: outcome is fixed, unverified, no_fix_needed, false_positive or failed. verified is true only for fixed, a fix proven by reproducing the flaw. An unverified run opened a pull request for a fix that was not proven: its verified is false, and pullRequestDraft is true when that pull request is a draft. Read verified, not the presence of pullRequestUrl, to decide whether a fix was verified. pullRequestUrl is null when no pull request was opened. finding is null for a dependency fix run, which belongs to a pentest's advisories and not to one finding.

{
  "run": { "id": "run_7d9f1b3a5c2e", "outcome": "fixed", "verified": true, "pullRequestUrl": "https://github.com/acme/shop/pull/12", "pullRequestDraft": false, "repository": "acme/shop" },
  "finding": { "id": "fnd_3b1f09c2a7d4", "title": "SQL injection in order lookup", "severity": "high", "assurance": "fixed", "cwe": ["CWE-89"], "file": "src/orders.js", "line": 42, "state": "open", "url": "..." }
}

finding.created:

{ "finding": { "id": "fnd_3b1f09c2a7d4", "title": "SQL injection in order lookup", "severity": "high", "assurance": "proven", "cwe": ["CWE-89"], "file": "src/orders.js", "line": 42, "state": "open", "url": "..." } }

finding.expert_reviewed: decision is confirmed, adjusted or rejected; severityBefore is the severity before an adjustment (otherwise null); note is what the researcher wrote; requested is true when your workspace asked for the review. Who the researcher is is not disclosed.

{
  "finding": { "id": "fnd_3b1f09c2a7d4", "title": "SQL injection in order lookup", "severity": "medium", "assurance": "proven", "cwe": ["CWE-89"], "file": "src/orders.js", "line": 42, "state": "open", "url": "..." },
  "decision": "adjusted",
  "severityBefore": "high",
  "note": "Reachable only by a signed-in staff account.",
  "requested": true
}

finding.state_changed: state is the new state and by is who decided: a member's e-mail address, api-key:<key name>, <code host user name> (pull request reply) or Jira.

{
  "finding": { "id": "fnd_3b1f09c2a7d4", "title": "SQL injection in order lookup", "severity": "high", "assurance": "proven", "cwe": ["CWE-89"], "file": "src/orders.js", "line": 42, "state": "accepted_risk", "url": "..." },
  "state": "accepted_risk",
  "by": "dana@acme.example"
}

ping:

{ "message": "This is a test event from Nullgap." }

#What is never included

Events carry titles, severities, weakness ids, file paths with a line number, states and links. They never carry source code, finding descriptions, proof or evidence, remediation advice, patches, the reason given for a triage decision, or credentials. To get the detail, call the API with the id: findings reference.

#The three headers

Deliveries follow the Standard Webhooks format, so its verification libraries work as they are.

HeaderValue
webhook-idThe event id. The same on every retry: de-duplicate on it.
webhook-timestampUnix time in seconds of this attempt. A retry carries a new timestamp.
webhook-signaturev1, followed by the base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw request body>.

The HMAC key is the endpoint's signing secret with the whsec_ prefix removed, base64-decoded.

#Verify the signature

Do these four things, in this order:

  1. Read the raw request body. Verify the bytes you received, not a re-serialised copy of the parsed JSON.
  2. Reject a webhook-timestamp more than five minutes from your clock, so a captured request cannot be replayed later.
  3. Compute the signature and compare it in constant time.
  4. Ignore a webhook-id you have already handled, and still answer 2xx.

Both examples below are complete receivers. Put the signing secret in the NULLGAP_WEBHOOK_SECRET environment variable. They listen on PORT (8080 by default) at /nullgap/webhook; put them behind your HTTPS front end.

#Node

Uses only node:http and node:crypto. Save as receiver.mjs and run node receiver.mjs.

import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.NULLGAP_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;
const MAX_BODY_BYTES = 1_000_000;

// Event ids already handled. In production keep these in a store all your instances share.
const seen = new Map();

export function verify(secret, id, timestamp, rawBody, signatureHeader) {
  if (!secret || !id || !/^\d+$/.test(timestamp ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
  // The header is "v1,<base64>". Accept a space-separated list, as the Standard Webhooks format allows.
  return String(signatureHeader ?? '')
    .split(' ')
    .some((part) => {
      const [version, value] = part.split(',');
      if (version !== 'v1' || !value) return false;
      const given = Buffer.from(value, 'base64');
      return given.length === expected.length && timingSafeEqual(given, expected);
    });
}

function alreadyHandled(id) {
  const now = Date.now();
  for (const [key, at] of seen) if (now - at > 48 * 3600 * 1000) seen.delete(key);
  if (seen.has(id)) return true;
  seen.set(id, now);
  return false;
}

function handle(event) {
  switch (event.type) {
    case 'finding.created':
      console.log(`new ${event.data.finding.severity} finding: ${event.data.finding.url}`);
      break;
    case 'ping':
      console.log('test event received');
      break;
    default:
      console.log(`event ${event.type} ${event.id}`);
  }
}

export const server = createServer((req, res) => {
  if (req.method !== 'POST' || req.url !== '/nullgap/webhook') {
    res.writeHead(404).end();
    return;
  }
  const chunks = [];
  let size = 0;
  req.on('data', (chunk) => {
    size += chunk.length;
    if (size <= MAX_BODY_BYTES) chunks.push(chunk);
  });
  req.on('end', () => {
    if (size > MAX_BODY_BYTES) {
      res.writeHead(413).end();
      return;
    }
    // The signature covers the exact bytes that were sent: verify before parsing.
    const rawBody = Buffer.concat(chunks).toString('utf8');
    const id = req.headers['webhook-id'];
    if (!verify(SECRET, id, req.headers['webhook-timestamp'], rawBody, req.headers['webhook-signature'])) {
      res.writeHead(401).end();
      return;
    }
    if (alreadyHandled(id)) {
      // A retry of something you already have: answer 2xx, or it is sent again.
      res.writeHead(200).end();
      return;
    }
    // Answer first, work afterwards: Nullgap waits 15 seconds for the status.
    res.writeHead(204).end();
    handle(JSON.parse(rawBody));
  });
});

server.listen(Number(process.env.PORT ?? 8080));

#Python

Standard library only. Save as receiver.py and run python3 receiver.py.

import base64
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ.get("NULLGAP_WEBHOOK_SECRET", "")  # whsec_...
TOLERANCE_SECONDS = 300
MAX_BODY_BYTES = 1_000_000

# Event ids already handled. In production keep these in a store all your instances share.
seen = {}


def secret_key(secret):
    raw = secret[len("whsec_"):] if secret.startswith("whsec_") else secret
    raw = raw.replace("-", "+").replace("_", "/")
    return base64.b64decode(raw + "=" * (-len(raw) % 4))


def verify(secret, event_id, timestamp, raw_body, signature_header):
    if not secret or not event_id or not (timestamp or "").isdigit():
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    signed = event_id.encode() + b"." + timestamp.encode() + b"." + raw_body
    expected = base64.b64encode(hmac.new(secret_key(secret), signed, hashlib.sha256).digest())
    # The header is "v1,<base64>". Accept a space-separated list, as the Standard Webhooks format allows.
    for part in (signature_header or "").split(" "):
        version, _, value = part.partition(",")
        if version == "v1" and hmac.compare_digest(value.encode(), expected):
            return True
    return False


def already_handled(event_id):
    now = time.time()
    for key in [k for k, at in seen.items() if now - at > 48 * 3600]:
        del seen[key]
    if event_id in seen:
        return True
    seen[event_id] = now
    return False


def handle(event):
    if event["type"] == "finding.created":
        finding = event["data"]["finding"]
        print("new", finding["severity"], "finding:", finding["url"])
    elif event["type"] == "ping":
        print("test event received")
    else:
        print("event", event["type"], event["id"])


class Receiver(BaseHTTPRequestHandler):
    def answer(self, status):
        self.send_response(status)
        self.send_header("Content-Length", "0")
        self.end_headers()

    def do_POST(self):
        if self.path != "/nullgap/webhook":
            return self.answer(404)
        length = int(self.headers.get("Content-Length") or 0)
        if length > MAX_BODY_BYTES:
            return self.answer(413)
        # The signature covers the exact bytes that were sent: verify before parsing.
        raw_body = self.rfile.read(length)
        event_id = self.headers.get("webhook-id")
        if not verify(SECRET, event_id, self.headers.get("webhook-timestamp"), raw_body, self.headers.get("webhook-signature")):
            return self.answer(401)
        if already_handled(event_id):
            # A retry of something you already have: answer 2xx, or it is sent again.
            return self.answer(200)
        # Answer first, work afterwards: Nullgap waits 15 seconds for the status.
        self.answer(204)
        handle(json.loads(raw_body))


if __name__ == "__main__":
    HTTPServer(("", int(os.environ.get("PORT", "8080"))), Receiver).serve_forever()

#Delivery and retries

  • Answer with any 2xx status within 15 seconds. The response body is never read.
  • Redirects are not followed: a 3xx answer counts as a failure.
  • Each event is stored before it is sent, so a restart on Nullgap's side does not lose one.
  • A timeout, a connection failure or any answer that is not 2xx is retried, up to ten attempts in all:
AttemptWait after the previous attemptTime since the first attempt
1none0
22.5 minutes2.5 minutes
35 minutes7.5 minutes
410 minutes17.5 minutes
520 minutes37.5 minutes
640 minutesabout 1 hour 18 minutes
71 hour 20 minutesabout 2 hours 38 minutes
82 hours 40 minutesabout 5 hours 18 minutes
95 hours 20 minutesabout 10 hours 38 minutes
1010 hours 40 minutesabout 21 hours 18 minutes

Retries are picked up twice a minute, so one can go out up to half a minute after it falls due. After the tenth failure the event is given up on.

Because a failed delivery is sent again, the same event can reach you more than once, and events can arrive out of order. De-duplicate on webhook-id, and read the current state from the API when the order matters.

#Answering 410

410 Gone means "stop sending me this event". That event is given up on at once and is not retried. Other error answers, 4xx included, are retried, because they may be a deployment in progress.

#Automatic switch-off

When five events in a row have been given up on (ten failed attempts each, or a 410), the endpoint is switched off. The card shows the reason: "Switched off after 5 events in a row could not be delivered". One successful delivery in between resets the count.

While an endpoint is off:

  • no new events are recorded for it, and events still waiting for a retry are dropped;
  • nothing is replayed when you switch it back on. Events from the gap are gone; read the API to catch up.

Switch it back on with Switch on on the card, or with an admin key:

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/wh_123"

#Rotate the secret

Choose Rotate secret on the endpoint's row and confirm. Like adding an endpoint, this is done in the console by a signed-in admin or owner; an API key cannot do it. The new secret is shown once.

The old secret stops being used at that moment: every attempt after the rotation, including retries of events recorded earlier, is signed with the new secret, and each delivery carries one signature. To change over without rejecting anything, let your receiver accept either secret for a short while: deploy it with both, rotate, then remove the old one.

If you lose the secret, rotate it. It cannot be read back.

#The test event

Send test on the endpoint's row, or the call below with an admin key, sends one ping event now and returns what happened: the console says it is sending, then shows the status code and how long the endpoint took to answer, or the reason it failed. It is signed like any other event, so it tests your verification too. It is sent once and not retried, and a failed test does not count towards the automatic switch-off.

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/wh_123/test"
{ "id": "evt_0a1b2c3d4e5f", "type": "ping", "at": "2026-11-16T09:30:00.000Z", "ok": true, "status": 204, "error": null, "attempts": 1, "durationMs": 182 }

#Redeliver an event

Redeliver next to an event in Deliveries, or the call below with an admin key, sends that event again now: the same event id and the same body, newly signed, so a receiver that de-duplicates on webhook-id treats it as the same event. Use it after your endpoint was down, or while you debug a receiver. It is sent once and not retried, whether or not the endpoint is switched on, and its entry in the delivery log is updated with one more attempt.

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/wh_123/deliveries/evt_0a1b2c3d4e5f/redeliver"

Only the events in the delivery log can be redelivered. An event recorded before events were kept for sending again answers 409 not_kept.

#The delivery log

Deliveries on the endpoint's row shows the latest state of the last 20 events sent to it: Delivered with the status code, Retrying with the time of the next attempt, or Failed with the reason, the number of attempts and how long the latest attempt took (durationMs). The same list is in the deliveries field of each endpoint in the API.

Reason shownMeaning
"the endpoint answered 500"Your endpoint answered with that status.
"the endpoint answered with a redirect, which is not followed"A 3xx answer. Register the final address.
"no answer within 15 seconds"The request timed out. Answer first and do the work afterwards.
"could not connect: the host name was not found"The name does not resolve. Check the address for a typo.
"could not connect: the endpoint refused the connection"Nothing is listening on that address and port.
"could not connect: the endpoint's TLS certificate was not accepted"The certificate is expired, self-signed or for another name.
"could not connect: the connection was closed before an answer" or "could not connect: the connection timed out"The connection was cut, or never completed.
"could not connect to the endpoint"Any other connection failure.
"the address resolves to a private network"The host name now points to a private address. Nothing was sent.

Adding, changing, rotating and removing an endpoint, and redelivering an event, are recorded in the audit log as webhook.created, webhook.updated, webhook.secret_rotated, webhook.deleted and webhook.redelivered.

#Remove an endpoint

Choose Remove on the row, or call DELETE with an admin key. Events still waiting for it are dropped with it.

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/wh_123"

Nullgap documentation