Receive webhook events
Push firewall, publish, exception request, audit, and configuration events to your own systems as signed, batched webhook deliveries.
Webhooks push namespace events out of Bytesafe as they happen: the firewall POSTs signed JSON batches to an HTTPS endpoint you run, so blocked installs, configuration changes, and publishes land in your SIEM, chat, or ticketing system without polling.
Webhooks belong to the namespace. Creating, editing, testing, and deleting them needs the ns:update:webhooks permission (part of the admin team's set); reading them and their deliveries only needs ns:access.
Create a webhook
In the dashboard, open Webhooks and click New webhook:
- Name and optional Description
- Status: Enabled
- Endpoint URL: a publicly reachable HTTPS endpoint you control
- Events: at least one event type (next section)
- Firewall access: optional, limits firewall events to the firewalls you pick (next section)
On create, the dialog shows the webhook's Signing secret (whsec_...). Copy it into your receiver's configuration; managers can view or rotate it later on the webhook's Overview tab.
The API equivalent is POST /v1/<namespace-id>/webhooks; the 201 response carries the plaintext secret once alongside the webhook. See the API reference.
Choose event types
The table follows the groups under Events on the webhook form. Each group has an entry for all of its events, such as All firewall events, and a Select all or Clear button.
| Picker group | Event types | Fires when | Firewall selection applies |
|---|---|---|---|
| Firewall traffic | firewall.blocked, firewall.exception-allowed, firewall.allowed | A rule blocked a download or publish, an exception let a matched request through, or a log-only rule matched | Yes |
| Firewall traffic | package.published, package.unlisted | A publish passed the upload rules and was forwarded upstream. Unlist is NuGet only | Yes |
| Exception requests | exception-request.created, .approved, .denied, .withdrawn | An exception request was made or changed status | Yes |
| Audit log | audit.<action>, for example audit.team.create | An action from the audit action catalog was recorded, whether it succeeded or failed | No |
| Configuration changes | config.firewall.created, .updated, .deleted, and config.webhook.* | A firewall or webhook changed successfully. The event carries the complete resource after the change | No |
Firewall access on the webhook form limits the groups marked Yes to the firewalls you pick. With nothing selected, they are delivered for every firewall.
Audit and configuration events overlap on purpose. Audit events record failures as well as successes, which suits a security log. Configuration events fire only on success and carry the full resource, so automation can mirror the new state without calling the API.
A trailing .* subscribes to a prefix, such as audit.team.*. A bare * is rejected, so select each group you want instead.
Two things the webhook form cannot change:
- System events (
webhook.rate_limited,webhook.test) are always delivered, so consumers can detect throttling and dropped events. - Firewall events from the
versionsexecution phase are never delivered, because one install can evaluate thousands of versions. Onlydownloadanduploaddecisions are delivered.
Events also lists Vulnerabilities event types as coming soon; they are disabled and not emitted yet.
Verify the endpoint
On the webhook's Overview tab, use Send a test event: pick the generic test event or a sample firewall event and click Send test. The result shows the HTTP status, duration, and your endpoint's response body, and the attempt is recorded as a delivery marked test. Subscriptions do not apply to tests. The API equivalent is POST /v1/<namespace-id>/webhooks/{webhook}/test.
Your receiver should verify every delivery's signature before trusting it. Deliveries follow the Standard Webhooks convention, so its libraries work as-is: verify the webhook-signature header (HMAC-SHA256 over webhook-id, webhook-timestamp, and the raw body) with your signing secret. Header formats and a worked verification example: Webhooks reference. The payload shapes are described by a published JSON Schema, linked from the picker, for generating receiver types.
Handle deliveries reliably
- Respond with a
2xxquickly; process the payload asynchronously if the work is slow. Attempts time out after 10 seconds, and redirects count as failures. - Expect batches: one delivery carries up to 100 events in a single
eventsarray. - Deliveries are at-least-once. The
webhook-idheader is stable across retries; deduplicate on it. - Watch for
webhook.rate_limitedevents with reasonbuffer_overflow: they mean events were dropped and there is a gap to reconcile against the firewall log or audit log, which remain the source of truth.
Rotate the secret
On the Overview tab, the Signing secret card has Reveal and Rotate. Rotating generates a new secret immediately; the previous secret keeps verifying deliveries for 24 hours, and during that window every delivery carries two signatures (space-separated in webhook-signature), so a receiver that matches either signature never breaks mid-rotation.
When deliveries fail
A failed delivery (non-2xx, timeout, or connection error) is retried on a backoff schedule of 30 seconds, 2 minutes, 10 minutes, 30 minutes, and 1 hour; a Retry-After header on 429 or 503 responses is honored up to 1 hour.
When all attempts fail, that batch is recorded as failed and the webhook is quarantined for 24 hours: deliveries pause, new events keep buffering, and delivery resumes automatically when the quarantine expires. The webhook's page shows a banner with the reason and a Release now button to resume earlier once the endpoint is fixed. Quarantine pauses deliveries to your endpoint; it never holds packages.
Monitor deliveries
The Deliveries tab keeps the recent deliveries for debugging; click a row for the exact signed payload and your endpoint's response. The Metrics tab charts delivered and failed deliveries, events sent and dropped, and delivery latency over selectable periods. Field-level detail: Webhooks reference.
Related
- Concept: Observability
- Reference: Webhooks, API, Audit log, Permissions
- How-to: Review the audit log, View logs
Prevent dependency confusion
Stop public registries from serving packages that share names with your internal packages.
Research advisories and malware
Search the advisory data behind your vulnerability rules, read a vulnerability's scores, exploitation status, and affected packages, and open the report behind a malware block.