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

# Webhooks

> Receive signed HTTP callbacks when payments, paywalls, and services change in your account.

Webhooks push signed HTTP callbacks to your server when events happen in your account — payments, paywall and service changes. Verify each request with the `X-Webhook-Signature` header. Your backend can grant access, update a ledger, or alert your team without polling [Transactions](https://docs.myproceeds.xyz/dashboard/transactions.md) or [Events](https://docs.myproceeds.xyz/dashboard/events.md).

> [!NOTE]
>
> Webhooks are configured from the dashboard only. There is no API to create or manage endpoints.

## Add an endpoint

In the dashboard, open **Webhooks** and click **Add endpoint**:

| Field | Description |
| - | - |
| **Endpoint URL** | The HTTPS URL Proceeds sends events to — for example `https://api.example.com/webhooks/proceeds`. |
| **Description** | Optional label to identify the endpoint. |
| **Events to send** | The event types this endpoint receives. Use **Select all** or pick individually. |

You can configure up to **20 endpoints**. Each endpoint can subscribe to a different set of events.

## Events

Choose which events each endpoint receives:

| Group | Event | Fires when |
| - | - | - |
| **Payments** | `payment.requested` | A `402` challenge was issued for a request. |
| | `payment.pending` | A Circle Nanopayment authorization was accepted into a Gateway batch (transaction is `Pending`). |
| | `payment.succeeded` | Payment settled and the protected request was proxied (`Completed`). |
| | `payment.failed` | Settlement or fulfillment failed. |
| **Paywalls** | `paywall.created` | A paywall was created. |
| | `paywall.updated` | A paywall was updated. |
| | `paywall.deleted` | A paywall was deleted. |
| **Services** | `service.created` | A service was created. |
| | `service.updated` | A service was updated. |
| | `service.deleted` | A service was deleted. |
| **Withdrawals** | `withdrawal.initiated` | The withdrawal was initiated. |
| | `withdrawal.burned` | Tokens burned. |
| | `withdrawal.attested` | Attestation received. |
| | `withdrawal.minted` | Tokens minted. |
| | `withdrawal.completed` | The withdrawal completed. |
| | `withdrawal.failed` | The withdrawal failed. |

> [!NOTE]
>
> Webhook `payment.*` names follow transaction state (`Pending` / `Completed` / `Failed`). They are not the dashboard Events `REQUEST` / `SUCCESS` / `ERROR` stream, and `GET /v1/events` is not a webhook payload.

## Verify each delivery

Verify `X-Webhook-Signature` with the endpoint's full `whsec_` secret before you grant access or update a ledger. Each endpoint has its own secret, shown in the endpoint list. Store it server-side.

| | |
| - | - |
| Signed string | `{timestamp}.{rawBody}` |
| Algorithm | HMAC-SHA256, lowercase hex |
| Header | `X-Webhook-Signature: t={timestamp},v1={hex}` |
| Key | full `whsec_…` (do not strip). Format `/^whsec_[0-9a-f]{64}$/` |

Pass the raw POST body, the `X-Webhook-Signature` header, and the endpoint secret into `verifyProceedsWebhook` (or the Python equivalent).

```typescript Node.js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto'

export function parseHeader(
  signatureHeader: string | undefined,
): { t: string; v1: string } | null {
  if (typeof signatureHeader !== 'string' || !signatureHeader) return null
  const parts: Record<string, string> = Object.create(null)
  for (const segment of signatureHeader.split(',')) {
    const eq = segment.indexOf('=')
    if (eq <= 0) continue
    parts[segment.slice(0, eq).trim()] = segment.slice(eq + 1).trim()
  }
  if (!parts.t || !parts.v1) return null
  return { t: parts.t, v1: parts.v1 }
}

function hexToBuffer(hex: string): Buffer | null {
  if (!hex || hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) return null
  try {
    return Buffer.from(hex, 'hex')
  } catch {
    return null
  }
}

export function verifyProceedsWebhook({
  rawBody,
  signatureHeader,
  secret,
}: {
  rawBody: Buffer | string
  signatureHeader: string | undefined
  secret: string
}): boolean {
  if (!secret.startsWith('whsec_')) {
    throw new TypeError('secret must start with whsec_')
  }
  const parsed = parseHeader(signatureHeader)
  if (!parsed) return false
  const provided = hexToBuffer(parsed.v1)
  if (!provided) return false
  const bodyUtf8 = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : String(rawBody)
  const expectedHex = createHmac('sha256', secret)
    .update(`${parsed.t}.${bodyUtf8}`, 'utf8')
    .digest('hex')
  const expected = Buffer.from(expectedHex, 'hex')
  if (provided.length !== expected.length) return false
  return timingSafeEqual(provided, expected)
}
```

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


def verify_proceeds_webhook(
    *,
    raw_body: bytes | str,
    signature_header: str | None,
    secret: str,
) -> bool:
    if not secret.startswith("whsec_"):
        raise TypeError("secret must start with whsec_")
    if not isinstance(signature_header, str) or not signature_header:
        return False

    parts: dict[str, str] = {}
    for segment in signature_header.split(","):
        eq = segment.find("=")
        if eq <= 0:
            continue
        key = segment[:eq].strip()
        value = segment[eq + 1 :].strip()
        if key:
            parts[key] = value

    t = parts.get("t")
    v1 = parts.get("v1")
    if not t or not v1:
        return False

    body_utf8 = (
        raw_body.decode("utf-8")
        if isinstance(raw_body, (bytes, bytearray))
        else str(raw_body)
    )
    signed_string = f"{t}.{body_utf8}".encode("utf-8")
    expected = hmac.new(secret.encode("utf-8"), signed_string, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1.lower())
```

> [!NOTE]
>
> Proceeds signs the **raw** request body. If your framework parses JSON first (`express.json()`, `req.json()`, and similar), verification fails. Use the unparsed bytes. The HMAC key is the full `whsec_…` secret — do not strip the prefix.

### Verify manually

Use these steps if you are not pasting the snippet above.

Proceeds sends a signature header like this (shown with newlines for clarity; the real header is one line):

```text theme={null}
X-Webhook-Signature:
t=1700000000,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

1. **Extract the timestamp and signature from the header.** Split on `,`, then `=`. `t` is the unix-seconds timestamp. `v1` is the hex HMAC. Ignore any other schemes.
2. **Prepare the signed payload.** Concatenate: timestamp (as a string) + `.` + the raw JSON body (exact POST bytes as utf8).
3. **Compute the expected signature.** HMAC-SHA256 of that string, using the full `whsec_…` secret as the key. Encoding is lowercase hex.
4. **Compare.** Constant-time compare (`timingSafeEqual` / `hmac.compare_digest`) of the hex-decoded buffers. Reject on mismatch or a malformed header.

> [!NOTE]
>
> There is **no** timestamp skew or replay window in Proceeds today. Do not implement a fake 5-minute check. Dedupe on envelope `id`.

## Delivery and retries

Proceeds expects a `2xx` within **10 seconds**. Non-`2xx` responses retry up to **3 attempts**, with backoff **2s / 4s / 8s**. Retryable status codes: `408`, `429`, `5xx`. Other `4xx` responses are not retried.

Open an endpoint's **Recent deliveries** to inspect history:

| Column | Meaning |
| - | - |
| Event | The event type delivered. |
| Status | `Succeeded` or failed. |
| Code | The HTTP status your endpoint returned. |
| Attempts | Delivery attempts used, out of 3. |
| Time | When the delivery was sent. |
| Resend | Dashboard replay of that delivery (not Resend.com). |

## Manage endpoints

The Webhooks list shows each endpoint's **Status** (active or paused), subscribed **Events**, **Last delivery**, and signing **Secret**. From there you can pause, edit, or delete an endpoint.

## Best practices

* Return `2xx` after verify and de-dupe; process asynchronously (10s timeout).
* De-dupe on envelope `id`.
* Subscribe narrowly — only enable the events each endpoint needs.

> [card] [Transactions](https://docs.myproceeds.xyz/dashboard/transactions.md)
>
> The payment state that `payment.*` events mirror.

> [card] [Events](https://docs.myproceeds.xyz/dashboard/events.md)
>
> The request lifecycle you can also inspect in the dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.