# Throttling

## Introduction

Protect your webhook endpoints from abuse and ensure fair resource usage with Webhooked's comprehensive rate limiting capabilities.

{% hint style="info" %}
Rate limiting is applied per client IP, keep it in mind
{% endhint %}

## Rate Limiting Algorithms

### Sliding Window

```yaml
throttling:
  enabled: true
  maxRequests: 1000
  window: 3600        # 1 hour sliding window
```

### Token Bucket Algorithm

The default algorithm used by Webhooked:

```yaml
throttling:
  enabled: true
  maxRequests: 100    # Bucket capacity
  window: 60          # Refill rate: 100 tokens per 60 seconds
  burst: 20           # Allow bursts up to 20 requests
```

**How it works:**

1. Bucket starts with `maxRequests` tokens
2. Each request consumes one token
3. Tokens refill at rate of `maxRequests/window`
4. Burst allows temporary exceeding of rate

### Request Queuing

#### Basic Queue Configuration

```yaml
throttling:
  enabled: true
  maxRequests: 100
  window: 60
  queueCapacity: 50         # Queue up to 50 requests
  queueTimeout: 5           # Wait max 5 seconds
  queueTimeoutCode: 503     # Return 503 on timeout
```

#### Queue Behavior

When rate limit is exceeded:

1. Request enters queue if capacity available
2. Waits for token to become available
3. Processes when token available or timeout
4. Returns configured status code on timeout

## Configuration

```yaml
specs:
  - throttling:
      enabled: true
      maxRequests: 1000     # Sustained rate
      window: 60            # Per minute
      burst: 50             # Allow burst of 50 requests
      burstWindow: 10       # Within 10 seconds
```

| Property           | Description             | Default | Example |
| ------------------ | ----------------------- | ------- | ------- |
| `enabled`          | Enable rate limiting    | `false` | `true`  |
| `maxRequests`      | Max requests per window | -       | `1000`  |
| `window`           | Time window (seconds)   | -       | `60`    |
| `burst`            | Burst capacity          | -       | `50`    |
| `burstWindow`      | Burst window (seconds)  | -       | `10`    |
| `queueCapacity`    | Request queue size      | `0`     | `100`   |
| `queueTimeout`     | Queue timeout (seconds) | `0`     | `5`     |
| `queueTimeoutCode` | Status code on timeout  | `503`   | `503`   |

## Common Configurations

### API Rate Limiting

Standard API rate limiting:

```yaml
specs:
  - throttling:
      enabled: true
      maxRequests: 10000    # 10K requests
      window: 3600          # Per hour
      burst: 100            # Allow small bursts
      burstWindow: 60       # Per minute
```

### Webhook Protection

Protect against webhook storms:

```yaml
specs:
  - throttling:
      enabled: true
      maxRequests: 100      # Conservative limit
      window: 60            # Per minute
      burst: 20             # Small burst allowance
      burstWindow: 10       # Quick burst window
```

### High-Traffic Configuration

For high-volume webhooks:

```yaml
specs:
  - throttling:
      enabled: true
      maxRequests: 50000    # 50K requests
      window: 60            # Per minute
      burst: 1000           # Large burst capacity
      burstWindow: 5        # 5 second burst
      queueCapacity: 500    # Queue excess requests
      queueTimeout: 10      # Wait up to 10 seconds
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.atom.codes/webhooked/configuration/throttling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.