# Webhook Proxy Documentation

## Overview

The Webhook Proxy service allows you to receive real-time notifications from your LND nodes via webhooks. It supports multiple event types and provides reliable delivery with automatic retries.

## Webhook Payload

When an event occurs, the service will send a POST request to your configured webhook URL with the following payload structure:

```json
{
  "node_id": "string",       // The ID of the LND node that generated the event
  "event_type": "string",    // Type of event (see Event Types below)
  "data": {                  // Event-specific data
    ...
  },
  "metadata": {
    "timestamp": 1708387874, // Unix timestamp of when the event was sent
    "attempt": 1,            // Current delivery attempt number
    "max_retries": 3,        // Maximum number of retry attempts
    "webhook_id": "string",  // ID of your webhook configuration
    "delivery_id": "string"  // Unique ID for this delivery attempt
  }
}
```

### HTTP Headers

Each webhook request includes the following headers:

```
Content-Type: application/json
X-Event-Type: <event_type>
X-Node-ID: <node_id>
X-Webhook-ID: <webhook_id>
X-Delivery-ID: <delivery_id>
X-Attempt: <current_attempt>
X-Max-Retries: <max_retries>
```

## Event Types

The service supports the following event types:

### 1. Invoice Events (`event_type: "invoice"`)
Triggered when an invoice is created, settled, or canceled.

```json
{
  "event_type": "invoice",
  "data": {
    "payment_hash": "string",
    "value_sat": "integer",
    "settled": "boolean",
    "creation_date": "integer",
    "settle_date": "integer",
    "payment_request": "string",
    "memo": "string",
    "state": "string"  // "OPEN", "SETTLED", or "CANCELED"
  }
}
```

### 2. Channel Events (`event_type: "channel"`)
Triggered for channel-related events (open, close, pending, active, inactive).

```json
{
  "event_type": "channel",
  "data": {
    "channel_point": "string",
    "capacity": "integer",
    "remote_pubkey": "string",
    "channel_id": "integer",
    "event": "string",  // "OPEN", "CLOSED", "ACTIVE", "INACTIVE", "PENDING"
    "close_type": "string"  // Only present for "CLOSED" events
  }
}
```

### 3. Block Events (`event_type: "block"`)
Triggered when a new block is detected.

```json
{
  "event_type": "block",
  "data": {
    "block_hash": "string",
    "block_height": "integer",
    "timestamp": "integer"
  }
}
```

### 4. Transaction Events (`event_type: "transaction"`)
Triggered when a new on-chain transaction is detected.

```json
{
  "event_type": "transaction",
  "data": {
    "tx_hash": "string",
    "amount": "integer",
    "num_confirmations": "integer",
    "block_hash": "string",
    "block_height": "integer",
    "timestamp": "integer",
    "is_outbound": "boolean"
  }
}
```

### 5. Peer Events (`event_type: "peer"`)
Triggered when peers connect or disconnect.

```json
{
  "event_type": "peer",
  "data": {
    "peer_pubkey": "string",
    "address": "string",
    "action": "string"  // "CONNECTED" or "DISCONNECTED"
  }
}
```

### 6. Chain Events (`event_type: "chain"`)
Triggered for blockchain-related events.

```json
{
  "event_type": "chain",
  "data": {
    "block_hash": "string",
    "block_height": "integer",
    "event": "string"  // "REORG" or "CONFIRMED"
  }
}
```

## Delivery Behavior

- The service will attempt to deliver webhooks immediately when events occur
- If delivery fails, it will retry with exponential backoff
- Default retry configuration: 3 attempts with 5-second initial delay
- Successful delivery requires a 2xx response (200, 201, or 202)
- Any non-2xx response is considered a failure and will trigger a retry
- Each retry includes the current attempt number in both the payload and headers

## Best Practices

1. **Idempotency**: Always use the `delivery_id` to deduplicate webhook deliveries
2. **Quick Response**: Your webhook endpoint should respond quickly (< 5 seconds)
3. **Async Processing**: If you need to do heavy processing, accept the webhook quickly and process asynchronously
4. **Verification**: Store your webhook configurations securely and verify the webhook ID in the headers
5. **Logging**: Use the delivery ID for correlation in your logs

## Error Handling

Your webhook endpoint should handle errors gracefully:

1. Return 2xx status code if you successfully received and queued/processed the webhook
2. Return 429 if you need the proxy to back off temporarily
3. Return 4xx for validation errors or if you explicitly don't want a retry
4. Return 5xx if you want the proxy to retry the delivery

{
  "type": "string",         // "status", "update", or "error"
  "details": {              // Event-specific details
    ...
  },
  "api": "string"           // Your node's endpoint (e.g. yournode.m.voltageapp.io)
}

{
  "type": "status",
  "details": {
    "status": "waiting_unlock"
  },
  "api": "yournode.m.voltageapp.io"
}

{
  "type": "status",
  "details": {
    "status": "waiting_init"
  },
  "api": "yournode.m.voltageapp.io"
}

{
  "type": "status",
  "details": {
    "status": "stopped"
  },
  "api": "yournode.m.voltageapp.io"
}

{
  "type": "update",
  "details": {
    "update_available": "true",
    "lnd_version": "0.17.0-beta",
    "volt_version": "v0.4.0"
  },
  "api": "yournode.m.voltageapp.io"
}

{
  "type": "status",
  "details": {
    "status": "waiting_unlock"
  },
  "api": "yournode.m.voltageapp.io"
}

curl -X POST https://yournode.m.voltageapp.io:8080/v1/unlockwallet \
  -d '{ "wallet_password": "cGFzc3dvcmQK", "stateless_init": true }'