Webhooks

A webhook pushes a namespace's events to your own systems as they happen, instead of you polling the logs: alert the team when a rule blocks a build, stream audit events into a SIEM, diff configuration changes against the git copy, or track successful publishes in an inventory.

A webhook subscribes an HTTPS endpoint to the event types you choose: firewall log decisions, audit events, configuration changes, and successful publishes. Every delivery is signed so the receiver can verify it, and failed deliveries are retried with at-least-once delivery from buffering to retry exhaustion.

This page is the exhaustive reference for what a receiver sees on the wire and how delivery behaves; for setup, see Receive webhook events. Management endpoints and permissions: API.

Event types

A subscription lists the event types to receive, either as exact types (firewall.blocked) or as a prefix with a trailing .* (firewall.*, audit.*, audit.team.*, config.*, package.*):

• A bare * is rejected; name the families you want.
• Exact firewall.*, config.*, and package.* names must be one of the types in the table above. Exact audit. and vulnerability. names are not checked against a list, so a subscription to a specific action keeps working when new actions are added.
• webhook.* types cannot be subscribed to: the system events are always delivered and cannot be turned off.
• Firewall events come from download and upload decisions only. Version filtering on a metadata request never produces events, however many versions it removes. A rule on the versions execution phase that blocks an artifact fetch counts as a download decision and is delivered.

audit.* and config.* deliberately overlap: the audit event is the security log (successes and failures, thin metadata), the config event is the automation feed (successes only, carrying the full resource state after the change).

Firewall scope

A webhook can optionally restrict the data-plane events, firewall.* and package.*, the only types that name a firewall, to a selection of the namespace's firewalls. An empty selection means every firewall. audit.*, config.*, and webhook.* events are never filtered by the selection. Selecting an unknown firewall is rejected at create/update; a firewall deleted after being selected simply stops matching and does not block later edits.

Envelope

Every delivery is one JSON object with a batch of events, oldest first, up to 100 events or 512 KB per delivery:

{
  "version": 1,
  "events": [
    {
      "id": "evt-01JZX2M8Q0V5T2C7N9R4W6YB3D",
      "type": "firewall.blocked",
      "time": "2026-07-13T09:30:00Z",
      "namespace": "ns-01KYA296JWEE36NDNRTJ4KM82Q",
      "data": {
        "firewall": "3e7f5cb806f26e3beae2",
        "executionPhase": "download",
        "blocked": true,
        "ecosystem": "npm",
        "packageName": "left-pad",
        "version": "1.3.0",
        "rule": "log-install-scripts-download",
        "message": "Install scripts detected: postinstall"
      }
    }
  ]
}

Event ids are stable: a retried delivery carries the same events with the same ids. Every payload shape is described by the published JSON Schema.

Event data

data holds the per-type payload, described below per event family. Fields marked "when set" are omitted when empty; every other field is always present (blocked is sent even when false).

firewall.*

One event per download or upload decision, carrying the fields of the firewall log entry, which documents each in detail:

audit.*

The fields of the audit event, which documents each in detail:

config.firewall.*

Upstream credentials inside config are always the redaction placeholder, never credential material.

config.webhook.*

package.*

Maven and PyPI upload one file per request, so one release can emit several events; deduplicate on ecosystem, packageName, and version.

The actor object

config.* and package.* events carry an actor object identifying who caused the change. Every field is omitted when empty:

System events

webhook.rate_limited reports delivery pressure on the webhook itself:

webhook.test carries the webhook id and a fixed message ("Test event").

JSON Schema

GET /schemas/webhook-events-v1.json on the dashboard origin returns a JSON Schema describing the envelope and every event payload, generated from the same types that render the events. It is a public contract document, served without authentication; use it to generate types or validate deliveries in the receiver.

Signing

Deliveries are signed per the Standard Webhooks convention. Three headers on every POST:

Each value in webhook-signature is an HMAC over the delivery: proof that it was produced by someone holding the webhook's signing secret and that the body was not modified in transit. The delivery id and timestamp are signed together with the body, so a captured signature cannot be reused for a different delivery, and the timestamp gives the receiver a way to reject stale deliveries.

The signature is computed as:

base64( HMAC-SHA256( key, "{webhook-id}.{webhook-timestamp}.{body}" ) )

key is the binary HMAC key inside the signing secret: the secret is whsec_ followed by the base64-encoded key. To verify a delivery:

1. Base64-decode the signing secret after the whsec_ prefix; the result is the HMAC key.
2. Join the webhook-id header, the webhook-timestamp header, and the request body with dots. Use the raw body bytes as received, before any JSON parsing.
3. Compute HMAC-SHA256 over that string with the key, and base64-encode the result.
4. Compare it in constant time against each space-separated v1, value; the delivery is authentic if any signature matches.

Standard Webhooks libraries implement exactly this, so a library call with the secret and the headers is usually all a receiver needs. The secret is returned on create and managers can reveal or rotate it later; see Receive webhook events.

For 24 hours after a secret rotation, deliveries carry two signatures, new and previous secret, so receivers on either secret keep verifying. Requests are sent with content-type: application/json and user agent bytesafe-d3-webhooks/1.

Delivery

Quarantined webhooks

When a batch exhausts all retry attempts, it is recorded as failed and dropped; that batch is not delivered again. The webhook itself is quarantined for 24 hours.

During quarantine, no deliveries are attempted, but new events keep buffering up to the buffer cap. When the quarantine expires, delivery resumes automatically with the buffered backlog.

To resume earlier, release the quarantine manually: the dashboard shows the quarantine reason and a Release now action on the webhook, and the API equivalent is POST .../webhooks/{webhook}/unquarantine.

Quarantine is a state of the webhook's deliveries, not of any package: the firewall never holds a package back for review.

Delivery records

The last 128 deliveries per webhook are kept as a ring buffer for debugging, each with the signed payload and the endpoint's response:

Metrics

Delivery metrics answer whether a receiver is keeping up: how many deliveries succeed and fail, how many events get through, and whether any are lost. Rising deliveriesFailed or any eventsDropped is the signal to check the endpoint and the delivery records.

GET .../webhooks/{webhook}/metrics?periodMinutes=... returns them per webhook; the dashboard's Metrics tab charts the same data. periodMinutes defaults to 1440 (24 hours) and caps at 10080 (7 days). Buckets are per minute; unlike firewall metrics, longer periods have no coarser rollup.

The response carries a buckets array and a totals object summing the same counters over the whole period:

Endpoint requirements

The endpoint URL must be http or https with a hostname that is not on the firewall's rejected-domain list, and it must resolve to a public address: requests to private, loopback, and link-local addresses are refused. The delivery client never follows redirects.

Related

• How-to: Receive webhook events
• Reference: API, Logs, Audit log, Permissions
• Concept: Observability