Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
List webhook endpointsGET /api/orgs/{org}/webhooksadmin
Add a webhook endpointPOST /api/orgs/{org}/webhooksconsole only (admin)
Change a webhook endpointPATCH /api/orgs/{org}/webhooks/{id}admin
Remove a webhook endpointDELETE /api/orgs/{org}/webhooks/{id}admin
Rotate a signing secretPOST /api/orgs/{org}/webhooks/{id}/rotateconsole only (admin)
Send a test eventPOST /api/orgs/{org}/webhooks/{id}/testadmin
Redeliver an eventPOST /api/orgs/{org}/webhooks/{id}/deliveries/{delivery}/redeliveradmin

#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

NameTypeRequiredDescription
orgstringyesThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
urlstringyesThe address to post events to. At most 500 characters. It must use https, be a public address, and carry no credentials and no fragment.
eventsarray of stringyesThe 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

StatusCodeWhen
400bad_requestThe address is not a valid https URL, carries credentials or a fragment, or events is empty or names an unknown event.
400private_addressThe address is a private, loopback or internal one.
409too_manyThe organisation already has 10 endpoints.
409duplicateThere is already an endpoint for this address.
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
eventsarray of stringnoThe events to receive. Replaces the whole list. At least one.
enabledbooleannoTrue 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

StatusCodeWhen
404not_foundThere is no webhook endpoint with that id in this organisation.
400bad_requestevents 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundThere 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundThere is no webhook endpoint with that id in this organisation.
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundThere 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.
deliverystringyesThe 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

StatusCodeWhen
404not_foundThere is no webhook endpoint with that id in this organisation, or the event is not among its recent deliveries.
409not_keptThe 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.

FieldTypeAlways presentDescription
idstringyesThe endpoint's id.
urlstringyesThe address events are posted to.
eventsarray of stringyesThe events this endpoint receives.
enabledbooleanyesTrue while events are being sent. Nullgap switches an endpoint off after five events in a row could not be delivered.
disabledReasonstring or nullyesWhy Nullgap switched the endpoint off. Null when it did not.
createdBystringyesWho added it.
createdAtstringyesWhen it was added.
deliveriesarray of WebhookDeliveryyesThe 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.

FieldTypeAlways presentDescription
idstringyesThe endpoint's id.
urlstringyesThe address events are posted to.
eventsarray of stringyesThe events this endpoint receives.
enabledbooleanyesTrue while events are being sent. Nullgap switches an endpoint off after five events in a row could not be delivered.
disabledReasonstring or nullyesWhy Nullgap switched the endpoint off. Null when it did not.
createdBystringyesWho added it.
createdAtstringyesWhen it was added.
deliveriesarray of WebhookDeliveryyesThe last twenty events sent to it, most recent first.
secretstringyesThe 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.

FieldTypeAlways presentDescription
idstringyesThe event's id. It is also the webhook-id header, and stays the same on every retry.
typestringyesThe event that was sent. ping is a test event.
atstringyesWhen the latest attempt was made.
okbooleanyesTrue when the endpoint answered with a 2xx status.
statusinteger or nullyesThe HTTP status the endpoint answered with. Null when there was no answer.
errorstring or nullyesWhy the attempt failed, in plain words. Null when it succeeded.
attemptsintegeryesHow many attempts have been made so far.
nextAttemptAtstringnoWhen the next attempt is due. Present only while a failed delivery is still being retried.
durationMsintegernoHow 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