nself webhooks

Inspect the outbound webhook outbox and delivery status. Useful for debugging event-driven integrations without leaving the terminal.

Quick start

# View pending and recently delivered webhook events
nself webhooks outbox

# Check delivery status of recent webhook attempts
nself webhooks status

Synopsis

nself webhooks <SUBCOMMAND> [FLAGS]

Description

nSelf supports two distinct webhook systems — understand which one you need before using this command:

• Hasura Event Triggers — fire when rows are inserted, updated, or deleted in your database. Configured inside the Hasura console or via migrations. Managed with nself db hasura. These are database-level hooks.
• nSelf outbound webhooks — fire on platform-level events such as a deployment completing, a service restarting, a circuit breaker opening, or a license renewal. Managed with nself webhooks. These are infrastructure-level hooks.

nself webhooks gives you visibility into the outbound webhook delivery queue — what events are pending, which were delivered successfully, and which failed with retries remaining.

To register or unregister webhook endpoints, edit the NSELF_WEBHOOK_ENDPOINTSvariable in your .env file and run nself build to apply the change.

Subcommands

nself webhooks outbox

Show the current outbox — events queued for delivery, pending retry, or recently delivered. By default shows the last 50 entries across all event types.

nself webhooks outbox
# ID       EVENT                   STATUS     ENDPOINT                        ATTEMPTS  NEXT RETRY
# 9f2a1c   deploy.completed        delivered  https://hooks.example.com/nsf   1/3       —
# 7d8b3e   service.restarted       delivered  https://hooks.example.com/nsf   1/3       —
# 5c4d7f   circuit_breaker.opened  failed     https://hooks.example.com/nsf   3/3       abandoned
# 3a2e9b   deploy.started          pending    https://hooks.example.com/nsf   0/3       now

nself webhooks outbox --status failed   # show only failed events
nself webhooks outbox --event deploy.*  # filter by event type glob
nself webhooks outbox --limit 100       # show more entries
nself webhooks outbox --json            # machine-readable

nself webhooks status

Show aggregate delivery statistics — success rate, failure rate, average latency, and count of events in each state.

nself webhooks status
# Webhook delivery summary (last 24h)
#
# Total events:     142
# Delivered:        138 (97.2%)
# Failed/abandoned:   4 (2.8%)
# Pending retry:      0
#
# Average latency:   312ms
# p95 latency:       890ms
#
# Endpoint:  https://hooks.example.com/nsf
#   Success: 138 / 142  (97.2%)
#   Failures: 4 (circuit_breaker.opened × 4 — connection refused)

Flags

Event types

Retry policy

Failed webhook deliveries are retried automatically with exponential back-off:

• Attempt 1: immediate
• Attempt 2: 30 seconds later
• Attempt 3: 5 minutes later

After 3 attempts, the event is marked abandoned and no further retries are made. Abandoned events remain visible in the outbox for 7 days.

Examples

Debug a failing webhook integration

# 1. Check overall delivery health
nself webhooks status

# 2. Find failed events
nself webhooks outbox --status failed

# 3. Get full detail on a specific event
nself webhooks outbox --json | jq '.[] | select(.id == "5c4d7f")'

Monitor deploy events in CI

# After deploying, wait for the deploy.completed event to be delivered
nself webhooks outbox --event deploy.completed --json | jq '.[0].status'

Check webhook latency over the past week

nself webhooks status --since 7d --json | jq '{total, delivered, avg_latency_ms}'

Configuring webhook endpoints

Add one or more webhook endpoints to your .env file:

# .env
NSELF_WEBHOOK_ENDPOINTS=https://hooks.example.com/nself,https://other.example.com/hook
NSELF_WEBHOOK_SECRET=your-hmac-signing-secret

Then run nself build to apply. All events are signed withNSELF_WEBHOOK_SECRET via HMAC-SHA256 in theX-nSelf-Signature header so your receiver can verify authenticity.

Related

• nself db — manage Hasura Event Triggers (database-level hooks)
• nself watchdog — circuit-breaker and self-healing status
• nself logs — view raw platform logs including webhook delivery logs
• nself build — apply configuration changes including webhook endpoint updates