Receive webhook events

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
• Endpoint URL: a publicly reachable HTTPS endpoint you control
• Subscribed events: at least one event type (next section)
• Enabled: on

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

Firewall traffic events, one per log entry, plus publish outcomes:

• firewall.blocked: a rule blocked a download or publish
• firewall.exception-allowed: a rule matched but an exception let the request through
• firewall.allowed: a log-only rule matched an allowed request
• package.published, package.unlisted: a publish passed the upload rules and was forwarded upstream (unlist is NuGet only)

Audit events mirror the audit action catalog as audit.<action>, for example audit.team.create or audit.firewall.rule.upsert.

Configuration events (config.firewall.*, config.webhook.*) are the automation feed: they fire on successful changes only and carry the complete resource after the change, so a consumer can mirror or react to the new state without a follow-up API call. The matching audit.* event is the security-log counterpart.

A trailing .* subscribes to a prefix: firewall.*, audit.*, config.*, package.*, or a narrower slice like audit.team.*. A bare * is rejected; combine the group wildcards for everything.

Traffic events (firewall.* and package.*) can additionally be scoped to specific firewalls in the picker; they are delivered for all firewalls unless you select specific ones. Audit and configuration events are never restricted by the selection.

Two things the picker cannot change:

• System events (webhook.rate_limited, webhook.test) are always delivered, so consumers can detect throttling and dropped events.
• Firewall events from the versions execution phase are never delivered; one install can evaluate thousands of versions. Webhooks carry download and upload decisions only, the same decisions worth alerting on.

The picker 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 2xx quickly; 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 events array.
• Deliveries are at-least-once. The webhook-id header is stable across retries; deduplicate on it.
• Watch for webhook.rate_limited events with reason buffer_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

Delivery attempt

Attempt outcome

Quarantine

Event matches subscription

Buffered per webhook

POST batch to endpoint

Deliveredinitial attempt or retry

Retry POST30s, 2m, 10m, 30m, 1h

Quarantined 24hfailed batch dropped; deliveries paused

Buffered delivery resumesafter 24h or Release now

Buffer holds new eventswhile quarantined

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