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

# Webhook

> Configure a Webhook destination for the GoldRush Pipeline API to deliver structured blockchain data via HTTP with retry and idempotency.

The Webhook destination delivers structured pipeline output to an HTTP endpoint. It supports configurable batching, retry with exponential backoff, and idempotency keys for safe retries.

## Configuration

```yaml theme={null}
destination:
  type: "webhook"
  url: "https://api.example.com/events"
  method: "POST"
  headers:
    Authorization: "Bearer ${WEBHOOK_TOKEN}"
    Content-Type: "application/json"
  batch_size: 1
  timeout_ms: 10000
  retry:
    max_attempts: 3
    backoff_ms: 1000
```

### Fields

| Field                | Type   | Required | Default | Description                |
| -------------------- | ------ | -------- | ------- | -------------------------- |
| `url`                | string | yes      | --      | Webhook endpoint URL       |
| `method`             | string | no       | `POST`  | HTTP method                |
| `headers`            | map    | no       | --      | Custom HTTP headers        |
| `batch_size`         | int    | no       | 1       | Records per request        |
| `timeout_ms`         | long   | no       | 10,000  | Request timeout (ms)       |
| `retry.max_attempts` | int    | no       | 3       | Max retry attempts         |
| `retry.backoff_ms`   | long   | no       | 1,000   | Initial backoff delay (ms) |

## Payload Format

The request body format depends on the `batch_size` setting.

### Single-record payload (`batch_size` = 1)

```json theme={null}
{
  "project": "analytics-prod",
  "stream": "hl_fills",
  "record": { "..." }
}
```

### Batched payload (`batch_size` > 1)

```json theme={null}
{
  "project": "analytics-prod",
  "stream": "hl_fills",
  "records": [ { "..." }, { "..." } ],
  "count": 2
}
```

## Idempotency

Every request includes an `X-Idempotency-Key` header derived from source metadata, allowing your endpoint to safely deduplicate retried deliveries.

| Mode          | Key Format                                    |
| ------------- | --------------------------------------------- |
| Single record | `{topic}-{partition}-{offset}`                |
| Batch         | `{topic}-{partition}-{minOffset}_{maxOffset}` |

## Retry Behavior

The destination retries failed requests using exponential backoff. The initial delay is set by `retry.backoff_ms` and doubles on each subsequent attempt, up to `retry.max_attempts`.

| Response      | Action                                                                 |
| ------------- | ---------------------------------------------------------------------- |
| 2xx           | Success - record acknowledged                                          |
| 429           | Retry, honoring `Retry-After` header if present; otherwise use backoff |
| 5xx           | Retry with exponential backoff                                         |
| 4xx (not 429) | Permanent failure - batch is skipped                                   |