Event Types¶

Complete reference of notification event types in Vigil.

Accuracy note

The backend treats btcwatch/src/notifications/event_types.rs as the single source of truth for event names. Payload shapes may vary by channel and may change over time; rely on the event name for routing.

Transaction Events¶

transaction.deposit¶

Incoming transaction detected in the mempool.

Trigger: Transaction sends funds to one of your monitored addresses

Payload Fields:

{
  "event": "transaction.deposit",
  "wallet_id": "wal_abc123",
  "txid": "abc123...",
  "amount_sats": 5000000,
  "address": "bc1qxyz...",
  "confirmations": 0,
  "fee_rate": 15
}

transaction.withdrawal¶

Outgoing transaction detected in the mempool.

Trigger: Transaction spends from your monitored UTXOs

Payload Fields:

{
  "event": "transaction.withdrawal",
  "wallet_id": "wal_abc123",
  "txid": "def456...",
  "amount_sats": 10000000,
  "outputs": [
    {
      "address": "bc1qabc...",
      "amount_sats": 9950000
    }
  ],
  "confirmations": 0,
  "fee_rate": 20
}

Confirmations

Confirmations can affect when you receive transaction-related notifications.

Theft Shield Events¶

theft_shield.incident_detected¶

Unauthorized transaction detected, Theft Shield responding.

Trigger: Transaction spending your UTXOs to non-whitelisted address

Payload Fields:

{
  "event": "theft_shield.incident_detected",
  "wallet_id": "wal_abc123",
  "incident_id": "inc_xyz789",
  "attacker_txid": "malicious123...",
  "attacker_fee_rate": 10,
  "protected_amount_sats": 50000000
}

theft_shield.defense_activated¶

Defense flow activated.

theft_shield.sweep_broadcast¶

Sweep transaction broadcast.

theft_shield.sweep_confirmed¶

Sweep transaction confirmed.

theft_shield.protection_failed¶

Protection failed to secure funds.

theft_shield.rbf_notification¶

RBF-related notification during incident handling.

theft_shield.config_created¶

Theft Shield configuration created for a wallet.

theft_shield.config_deleted¶

Theft Shield configuration deleted for a wallet.

theft_shield.monitoring_toggled¶

Theft Shield monitoring toggled on/off.

theft_shield.activated¶

Theft Shield activated.

theft_shield.payment_processing¶

Theft Shield fee/payment is processing.

theft_shield.ready_for_activation¶

Theft Shield is ready to be activated.

Wallet Events¶

Current behavior

The backend has internal wallet sync states, but wallet.sync_complete / wallet.sync_error are not currently part of the backend notification event type constants.

Payment Events¶

payment.detected¶

Payment detected by the system.

payment.confirmed¶

Payment confirmed.

PSBT Events¶

psbt.generated¶

PSBT generated.

psbt.updated¶

PSBT updated.

psbt.invalidated¶

PSBT invalidated.

System Events¶

System events

The backend allows flexible system.* event names, but system events are not currently enumerated as constants.

Event Frequency¶

Event	Typical Frequency
`transaction.deposit`	Per incoming tx
`transaction.withdrawal`	Per outgoing tx
`transaction.*`	Per deposit/withdrawal
`theft_shield.*`	Rare (incidents only)
`wallet.sync_*`	Initial setup, resyncs
`payment.*`	Monthly/yearly
`system.*`	Occasional

Enabling/Disabling Events¶

Not all events can be disabled:

Event	User Control
Transaction events	✅ Configurable
Theft Shield events	✅ Configurable
Payment events	✅ Configurable
PSBT events	✅ Configurable
System events	⚠️ Varies by event

Back to: Notifications Overview →