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

# Webhooks Quick Start

> Receive real-time notifications for billing events

Webhooks notify your application when billing events occur in Alguna. Set up webhooks to get instant updates when invoices are issued, payments processed, and subscriptions change.

***

## How Webhooks Work

When an event occurs (like an invoice being paid), Alguna sends a notification to a URL you specify. Your application can then take action based on that event.

```mermaid theme={null}
sequenceDiagram
    participant Alguna
    participant YourApp

    Note over Alguna: Event occurs (e.g., invoice paid)
    Alguna->>YourApp: Send webhook notification
    YourApp-->>Alguna: Acknowledge receipt
```

***

## Setting Up Webhooks

### Step 1: Add a Webhook Endpoint

1. Navigate to **Settings → Webhooks**
2. Click **Add Endpoint**
3. Enter your webhook URL (provided by your development team)
4. Click **Save**

### Step 2: Select Events

Choose which events you want to receive:

1. Click on your endpoint
2. Select the events you want to subscribe to
3. Click **Save**

### Step 3: Copy the Webhook Secret

1. After saving, copy the **Webhook Secret**
2. Share this with your development team for signature verification

<Warning>
  The webhook secret is only shown once. Copy it immediately and store it securely.
</Warning>

***

## Available Events

### Subscription Events

| Event                                | When It's Sent                        |
| ------------------------------------ | ------------------------------------- |
| `subscription.activated`             | A subscription becomes active         |
| `subscription.started`               | A subscription reaches its start date |
| `subscription.cancelation_scheduled` | A cancellation is scheduled           |
| `subscription.canceled`              | A subscription is canceled            |

### Invoice Events

| Event            | When It's Sent                   |
| ---------------- | -------------------------------- |
| `invoice.issued` | An invoice is sent to a customer |
| `invoice.paid`   | An invoice is fully paid         |

### Payment Events

| Event             | When It's Sent           |
| ----------------- | ------------------------ |
| `payment.created` | A payment is initiated   |
| `payment.updated` | A payment status changes |

### Credit Events

| Event                              | When It's Sent                           |
| ---------------------------------- | ---------------------------------------- |
| `account.credits.granted`          | Credits are added to a customer          |
| `account.credits.balance_depleted` | A customer's credit balance reaches zero |

### Other Events

| Event                        | When It's Sent          |
| ---------------------------- | ----------------------- |
| `checkout.session.completed` | A checkout is completed |
| `refund.updated`             | A refund status changes |

***

## Testing Webhooks

Send test events to verify your setup:

1. Go to **Settings → Webhooks**
2. Select your endpoint
3. Click **Send Test Event**
4. Choose an event type
5. Verify the event was received

***

## Viewing Webhook History

Track webhook deliveries:

1. Go to **Settings → Webhooks**
2. Select your endpoint
3. Click **Message Logs**
4. View delivery status, timestamps, and responses

***

## Retry Policy

If delivery fails, Alguna retries automatically:

| Attempt | Wait Time  |
| ------- | ---------- |
| 1       | Immediate  |
| 2       | 5 seconds  |
| 3       | 5 minutes  |
| 4       | 30 minutes |
| 5       | 2 hours    |
| 6       | 5 hours    |
| 7       | 10 hours   |

After 7 failed attempts over 5 days, the endpoint is disabled.

***

## Troubleshooting

### Webhook Not Received

1. Check the endpoint URL is correct
2. Verify the endpoint is publicly accessible
3. Review **Message Logs** for error details
4. Ensure your server responds within 15 seconds

### Endpoint Disabled

1. Check **Message Logs** for failure reasons
2. Fix any issues with your endpoint
3. Click **Enable** to reactivate

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Test First" icon="flask">
    Use test events before going live.
  </Card>

  <Card title="Monitor Logs" icon="chart-line">
    Regularly check webhook logs for failures.
  </Card>

  <Card title="Secure Secrets" icon="shield">
    Never expose your webhook secret publicly.
  </Card>

  <Card title="Quick Response" icon="bolt">
    Ensure your endpoint responds within 15 seconds.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Event Reference" icon="list" href="/api-reference/webhooks">
    See all webhook events and payloads.
  </Card>

  <Card title="Automations" icon="robot" href="/automations/overview">
    Automate workflows based on events.
  </Card>
</CardGroup>