> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valmi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Subscribe to events via webhooks

## Webhook Events

Valmi Value can send webhooks for the following events:

* `invoice.created` - Invoice generated
* `invoice.paid` - Invoice paid
* `outcome.completed` - Outcome achieved
* `payment.successful` - Payment processed
* `subscription.created` - Subscription created
* `subscription.updated` - Subscription updated
* `subscription.cancelled` - Subscription cancelled

## Configuring Webhooks

1. Navigate to **Settings** → **Webhooks**
2. Click **Add Webhook**
3. Configure:
   * **URL**: Your webhook endpoint
   * **Events**: Which events to subscribe to
   * **Secret**: Webhook secret for verification
4. Save

## Webhook Payload

Webhooks send POST requests with JSON payloads:

```json theme={null}
{
  "event": "invoice.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "account_id": "account_xyz789",
    "amount": 1000.00,
    "currency": "USD"
  }
}
```

## Webhook Security

Verify webhook authenticity using the webhook secret:

```python theme={null}
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected_signature)
```

## Webhook Retries

Webhooks are retried if your endpoint returns an error:

* **Retry Schedule**: 1min, 5min, 15min, 1hr, 6hr, 24hr
* **Max Retries**: 6 attempts
* **Timeout**: 30 seconds per attempt

## Testing Webhooks

Test webhooks using the webhook test endpoint:

```bash theme={null}
curl -X POST https://api.valmi.io/v1/webhooks/test \
  -H "Authorization: Bearer sk_api_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "webhook_abc123",
    "event": "invoice.created"
  }'
```