API reference
Outbound webhooks
Endpoints of yours that Nullgap sends events to.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| List webhook endpoints | GET /api/orgs/{org}/webhooks | admin |
| Add a webhook endpoint | POST /api/orgs/{org}/webhooks | console only (admin) |
| Change a webhook endpoint | PATCH /api/orgs/{org}/webhooks/{id} | admin |
| Remove a webhook endpoint | DELETE /api/orgs/{org}/webhooks/{id} | admin |
| Rotate a signing secret | POST /api/orgs/{org}/webhooks/{id}/rotate | console only (admin) |
| Send a test event | POST /api/orgs/{org}/webhooks/{id}/test | admin |
| Redeliver an event | POST /api/orgs/{org}/webhooks/{id}/deliveries/{delivery}/redeliver | admin |
#List webhook endpoints
GET /api/orgs/{org}/webhooks
Answers the organisation's webhook endpoints, each with its last twenty deliveries. Signing secrets are not returned. This is a plain list, not a paged one.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks"
Answer (200, application/json)
Every webhook endpoint of the organisation.
An array of Webhook.
[
{
"id": "wh_6e1f3b9d20c8",
"url": "https://hooks.acme.example/nullgap",
"events": [
"finding.created"
],
"enabled": true,
"disabledReason": "Switched off after 5 events in a row could not be delivered",
"createdBy": "dana@acme.example",
"createdAt": "2026-10-20T14:05:00.000Z",
"deliveries": [
{
"id": "evt_2c7a9e41b0d3",
"type": "finding.created",
"at": "2026-11-16T09:30:00.000Z",
"ok": true,
"status": 200,
"error": "the endpoint answered 503",
"attempts": 1,
"nextAttemptAt": "2026-11-16T09:35:00.000Z",
"durationMs": 182
}
]
}
]
#Add a webhook endpoint
POST /api/orgs/{org}/webhooks
Registers an address that Nullgap posts signed events to, and answers it with its signing secret, once. Where findings are sent is a sensitive setting, so this needs a person signed in to the console (an API key is refused), with a recent second-factor check when their account has one. An organisation can have up to 10 endpoints.
Who may call it: A signed-in admin or owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | The address to post events to. At most 500 characters. It must use https, be a public address, and carry no credentials and no fragment. |
events | array of string | yes | The events to receive. At least one; duplicates are dropped. |
Answer (200, application/json)
A WebhookWithSecret object.
{
"id": "wh_6e1f3b9d20c8",
"url": "https://hooks.acme.example/nullgap",
"events": [
"finding.created"
],
"enabled": true,
"disabledReason": "Switched off after 5 events in a row could not be delivered",
"createdBy": "dana@acme.example",
"createdAt": "2026-10-20T14:05:00.000Z",
"deliveries": [
{
"id": "evt_2c7a9e41b0d3",
"type": "finding.created",
"at": "2026-11-16T09:30:00.000Z",
"ok": true,
"status": 200,
"error": "the endpoint answered 503",
"attempts": 1,
"nextAttemptAt": "2026-11-16T09:35:00.000Z",
"durationMs": 182
}
],
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | The address is not a valid https URL, carries credentials or a fragment, or events is empty or names an unknown event. |
| 400 | private_address | The address is a private, loopback or internal one. |
| 409 | too_many | The organisation already has 10 endpoints. |
| 409 | duplicate | There is already an endpoint for this address. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Change a webhook endpoint
PATCH /api/orgs/{org}/webhooks/{id}
Changes which events an endpoint receives, or switches it on or off. Switching an endpoint back on clears the reason Nullgap switched it off and starts its failure count again. The address cannot be changed: add a new endpoint instead. Unlike adding an endpoint, this works with an admin API key.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
events | array of string | no | The events to receive. Replaces the whole list. At least one. |
enabled | boolean | no | True to send events, false to stop. Events queued for a switched-off endpoint are dropped, not held. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":["finding.state_changed"],"enabled":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/ID"
Answer (200, application/json)
A Webhook object.
{
"id": "wh_6e1f3b9d20c8",
"url": "https://hooks.acme.example/nullgap",
"events": [
"finding.created"
],
"enabled": true,
"disabledReason": "Switched off after 5 events in a row could not be delivered",
"createdBy": "dana@acme.example",
"createdAt": "2026-10-20T14:05:00.000Z",
"deliveries": [
{
"id": "evt_2c7a9e41b0d3",
"type": "finding.created",
"at": "2026-11-16T09:30:00.000Z",
"ok": true,
"status": 200,
"error": "the endpoint answered 503",
"attempts": 1,
"nextAttemptAt": "2026-11-16T09:35:00.000Z",
"durationMs": 182
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no webhook endpoint with that id in this organisation. |
| 400 | bad_request | events is empty or names an unknown event, or enabled is not true or false. |
#Remove a webhook endpoint
DELETE /api/orgs/{org}/webhooks/{id}
Deletes the endpoint. Events still waiting to be sent to it are dropped.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/ID"
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no webhook endpoint with that id in this organisation. |
#Rotate a signing secret
POST /api/orgs/{org}/webhooks/{id}/rotate
Replaces the endpoint's signing secret and answers the new one, once. Events are signed with the new secret from the next attempt on; the old one is not used again. Like adding an endpoint, this needs a person signed in to the console.
Who may call it: A signed-in admin or owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Answer (200, application/json)
A WebhookWithSecret object.
{
"id": "wh_6e1f3b9d20c8",
"url": "https://hooks.acme.example/nullgap",
"events": [
"finding.created"
],
"enabled": true,
"disabledReason": "Switched off after 5 events in a row could not be delivered",
"createdBy": "dana@acme.example",
"createdAt": "2026-10-20T14:05:00.000Z",
"deliveries": [
{
"id": "evt_2c7a9e41b0d3",
"type": "finding.created",
"at": "2026-11-16T09:30:00.000Z",
"ok": true,
"status": 200,
"error": "the endpoint answered 503",
"attempts": 1,
"nextAttemptAt": "2026-11-16T09:35:00.000Z",
"durationMs": 182
}
],
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no webhook endpoint with that id in this organisation. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Send a test event
POST /api/orgs/{org}/webhooks/{id}/test
Sends one signed ping event to the endpoint now and waits for the outcome, up to 15 seconds. It is sent whether or not the endpoint is switched on, and is not retried. A test that the endpoint refuses still answers 200: read ok, status and error in the answer. The delivery is added to the endpoint's recent deliveries.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/ID/test"
Answer (200, application/json)
A WebhookDelivery object.
{
"id": "evt_2c7a9e41b0d3",
"type": "finding.created",
"at": "2026-11-16T09:30:00.000Z",
"ok": true,
"status": 200,
"error": "the endpoint answered 503",
"attempts": 1,
"nextAttemptAt": "2026-11-16T09:35:00.000Z",
"durationMs": 182
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no webhook endpoint with that id in this organisation. |
#Redeliver an event
POST /api/orgs/{org}/webhooks/{id}/deliveries/{delivery}/redeliver
Sends one of the endpoint's recent deliveries again now, with the same event id and the same body, newly signed, and waits for the outcome, up to 15 seconds. A receiver that de-duplicates on webhook-id treats it as the same event. It is sent whether or not the endpoint is switched on, and is not retried. A redelivery the endpoint refuses still answers 200: read ok, status and error. The delivery's entry in the recent deliveries is updated, with attempts one higher. Takes no body.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
delivery | string | yes | The id of the event, from the endpoint's deliveries, such as evt_2c7a9e41b0d3. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks/ID/deliveries/deliveries/redeliver"
Answer (200, application/json)
A WebhookDelivery object.
{
"id": "evt_2c7a9e41b0d3",
"type": "finding.created",
"at": "2026-11-16T09:30:00.000Z",
"ok": true,
"status": 200,
"error": "the endpoint answered 503",
"attempts": 1,
"nextAttemptAt": "2026-11-16T09:35:00.000Z",
"durationMs": 182
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no webhook endpoint with that id in this organisation, or the event is not among its recent deliveries. |
| 409 | not_kept | The delivery was recorded before events were kept for sending again. |
#Objects
The objects the operations above take and return.
#Webhook
An address of yours that Nullgap posts signed events to.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The endpoint's id. |
url | string | yes | The address events are posted to. |
events | array of string | yes | The events this endpoint receives. |
enabled | boolean | yes | True while events are being sent. Nullgap switches an endpoint off after five events in a row could not be delivered. |
disabledReason | string or null | yes | Why Nullgap switched the endpoint off. Null when it did not. |
createdBy | string | yes | Who added it. |
createdAt | string | yes | When it was added. |
deliveries | array of WebhookDelivery | yes | The last twenty events sent to it, most recent first. |
#WebhookWithSecret
A webhook endpoint together with its signing secret. This is the only time the secret is returned.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The endpoint's id. |
url | string | yes | The address events are posted to. |
events | array of string | yes | The events this endpoint receives. |
enabled | boolean | yes | True while events are being sent. Nullgap switches an endpoint off after five events in a row could not be delivered. |
disabledReason | string or null | yes | Why Nullgap switched the endpoint off. Null when it did not. |
createdBy | string | yes | Who added it. |
createdAt | string | yes | When it was added. |
deliveries | array of WebhookDelivery | yes | The last twenty events sent to it, most recent first. |
secret | string | yes | The signing secret, starting with whsec_. Use it to verify the webhook-signature header. Store it now: it cannot be read again. |
#WebhookDelivery
The latest state of one event sent to a webhook endpoint.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The event's id. It is also the webhook-id header, and stays the same on every retry. |
type | string | yes | The event that was sent. ping is a test event. |
at | string | yes | When the latest attempt was made. |
ok | boolean | yes | True when the endpoint answered with a 2xx status. |
status | integer or null | yes | The HTTP status the endpoint answered with. Null when there was no answer. |
error | string or null | yes | Why the attempt failed, in plain words. Null when it succeeded. |
attempts | integer | yes | How many attempts have been made so far. |
nextAttemptAt | string | no | When the next attempt is due. Present only while a failed delivery is still being retried. |
durationMs | integer | no | How long the latest attempt took, from sending to the answer or to giving up, in milliseconds. Absent on deliveries recorded before it was measured. |
Nullgap documentation