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.
- Open Integrations and find the Webhooks card. Choose Add webhook.
- Enter the Endpoint address and tick the events you want. All are ticked to begin with.
- Choose Add webhook. The Signing secret is shown once. Copy it into your secret store before closing the dialog.
Rules for the address:
| Rule | Detail |
|---|---|
| Scheme | https only. |
| Host | A public address. Private, loopback and link-local addresses are refused, both by name and by what the name resolves to at each delivery. |
| Form | No user name or password in the URL, no fragment, at most 500 characters. |
| Limits | Up 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
| Event | Sent when |
|---|---|
review.completed | A pull request review finished, whether or not it reported anything. |
review.failed | A review stopped with an error. A review that was skipped or cancelled sends nothing. |
pentest.started | A pentest was accepted and queued: started in the console, through the API, from Slack, as a retest or by a schedule. |
pentest.completed | A pentest or retest finished. |
pentest.failed | A pentest stopped with an error. A cancelled pentest sends nothing. |
remediation.completed | A fix run finished, with any outcome. A fix run that is stopped by an error or cancelled sends nothing. |
finding.created | A 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_changed | Someone 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_reviewed | A Nullgap security researcher decided on a finding: an expert review you asked for, or researcher validation under contract. |
ping | Someone 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": {}
}
| Field | Meaning |
|---|---|
id | The event id. The same on every retry and equal to the webhook-id header. Each endpoint gets its own id for the same occurrence. |
type | One of the events above. |
createdAt | When the event was recorded, not when this attempt was sent. |
organisation | Your organisation's slug. |
data | Depends 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"
}
| Field | Values |
|---|---|
severity | critical, high, medium, low, info |
assurance | The 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. |
cwe | A list of weakness ids, possibly empty. |
file, line | Where the finding is, or null when it has no code location. |
state | open, patched, accepted_risk, false_positive |
url | The 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.
| Header | Value |
|---|---|
webhook-id | The event id. The same on every retry: de-duplicate on it. |
webhook-timestamp | Unix time in seconds of this attempt. A retry carries a new timestamp. |
webhook-signature | v1, 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:
- Read the raw request body. Verify the bytes you received, not a re-serialised copy of the parsed JSON.
- Reject a
webhook-timestampmore than five minutes from your clock, so a captured request cannot be replayed later. - Compute the signature and compare it in constant time.
- Ignore a
webhook-idyou have already handled, and still answer2xx.
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
2xxstatus within 15 seconds. The response body is never read. - Redirects are not followed: a
3xxanswer 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
2xxis retried, up to ten attempts in all:
| Attempt | Wait after the previous attempt | Time since the first attempt |
|---|---|---|
| 1 | none | 0 |
| 2 | 2.5 minutes | 2.5 minutes |
| 3 | 5 minutes | 7.5 minutes |
| 4 | 10 minutes | 17.5 minutes |
| 5 | 20 minutes | 37.5 minutes |
| 6 | 40 minutes | about 1 hour 18 minutes |
| 7 | 1 hour 20 minutes | about 2 hours 38 minutes |
| 8 | 2 hours 40 minutes | about 5 hours 18 minutes |
| 9 | 5 hours 20 minutes | about 10 hours 38 minutes |
| 10 | 10 hours 40 minutes | about 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 shown | Meaning |
|---|---|
| "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