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

# Webhooks

> Pay link webhooks: HMAC-SHA256 signed with a timestamp in X-Xenarch-Signature, seven event types, retried with backoff for up to 24 hours.

Xenarch sends an HTTPS `POST` to your endpoint when something happens on one of your pay links. Each delivery is signed with the link's `webhook_secret`, so you can check that it came from Xenarch and was not replayed.

## Set the endpoint

Pass `webhook_url` in the link params when you create the link, or set it later:

```bash CLI theme={null}
npx xenarch links webhook set <link_id> \
  --url https://example.com/xenarch-webhook \
  --events payment.confirmed,subscription.renewed \
  --confirm
```

```bash API theme={null}
curl -X PUT https://api.xenarch.dev/v1/links/<link_id>/webhook \
  -H "Authorization: Bearer xm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/xenarch-webhook", "event_types": ["payment.confirmed", "subscription.renewed"], "enabled": true}'
```

The URL must use `https`, and Xenarch refuses URLs that resolve to private addresses. Omit `event_types` (or send `null`) to receive every event. `enabled: false` pauses deliveries without removing the endpoint.

The `webhook_secret` (`whsec_` plus 64 hex characters) is returned when you create the link. To get a new one, rotate it with `POST /v1/links/{link_id}/webhook/rotate-secret` or `xenarch links webhook rotate <link_id>`. The old secret stops working, both for webhook signatures and for the [usage endpoint](https://docs.xenarch.com/payments/subscriptions.md#metered-billing).

## Events

| Event | Sent when |
| - | - |
| `payment.confirmed` | A payment for the expected amount is verified on Base |
| `payment.underpaid` | A payment below the expected amount (or below `min_amount`) is verified |
| `payment.overpaid` | A payment above the expected amount (or above `max_amount`) is verified |
| `subscription.renewed` | You collect a permit or metered subscription charge on-chain and Xenarch verifies it. A reminder-mode renewal arrives as a `payment.*` event. |
| `subscription.status_changed` | A subscriber's status changes, for example to `failed` (suspended), `exhausted` or `cancelled`, or back to `active` |
| `charge.booked` | A metered subscription crosses its billing threshold and a charge is booked |
| `charge.settled` | Booked metered charges are collected on-chain |

`xenarch links webhook test <link_id>` sends a test delivery to your endpoint.

## Request format

```http theme={null}
POST /xenarch-webhook HTTP/1.1
Content-Type: application/json
X-Xenarch-Signature: t=1794916800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
X-Xenarch-Event: payment.confirmed
X-Xenarch-Delivery: 0b6f8a52-5d1e-4c7e-9a43-2f1c0e7d9b10
```

```json theme={null}
{
  "event_type": "payment.confirmed",
  "link_id": "JJjIwDyV4N1CG9g8AHMxfdJ9",
  "data": {
    "tx_hash": "0x...",
    "block_number": 38120455,
    "from": "0xBuyerWallet...",
    "to": "0xYourWallet...",
    "value_micro_usdc": 25000000,
    "expected_micro_usdc": 25000000,
    "single_use": false,
    "attempt_id": "c1d2e3f4-..."
  }
}
```

Amounts are in micro-USDC (6 decimals), so `25000000` is 25 USDC. Payment events can also carry `reference_id` (invoice number), `client_reference_id`, `subid`, and `tip_micro_usdc` with `subtotal_micro_usdc` when they apply. Subscription and charge events carry `subscription_id`. `subscription.status_changed` carries `old_status` and `new_status`.

## Verify the signature

`X-Xenarch-Signature` has the form `t=<unix_seconds>,v1=<hex>`, where `v1` is HMAC-SHA256, keyed with your `webhook_secret`, of the string `<t>.<raw_body>`. Reject the request when the signature does not match or when `t` is more than 300 seconds from your clock. Always verify the raw request body, not a re-serialized object.

```ts TypeScript (@xenarch/sdk) theme={null}
import { webhooks } from "@xenarch/sdk";

export async function POST(request: Request): Promise<Response> {
  const raw = await request.text();
  const sig = request.headers.get("X-Xenarch-Signature");
  if (!(await webhooks.verify(raw, sig, process.env.XENARCH_WEBHOOK_SECRET!))) {
    return new Response("bad signature", { status: 401 });
  }
  const event = JSON.parse(raw);
  // event.event_type, event.link_id, event.data
  return new Response("ok");
}
```

```python Python (xenarch) theme={null}
import json
import os

from fastapi import FastAPI, Request, Response
from xenarch import webhooks

app = FastAPI()


@app.post("/xenarch-webhook")
async def xenarch_webhook(request: Request) -> Response:
    body = await request.body()
    sig = request.headers.get("X-Xenarch-Signature", "")
    if not webhooks.verify(body, sig, os.environ["XENARCH_WEBHOOK_SECRET"]):
        return Response(status_code=401)
    event = json.loads(body)
    # event["event_type"], event["link_id"], event["data"]
    return Response(status_code=200)
```

TypeScript: `webhooks.verify(payload, signatureHeader, secret, { toleranceSeconds?, throwOnFailure? })` returns a `Promise<boolean>`. Python: `webhooks.verify(payload, signature_header, secret, *, tolerance_seconds=300, raise_on_failure=False)` returns a `bool`. Both default to a 300 second window.

## Retries

A delivery counts as delivered when your endpoint answers with a 2xx status. Otherwise Xenarch retries after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then every 6 hours, until 24 hours have passed since the first attempt. A 4xx response other than 408 or 429 stops retries for that delivery at once. After 5 failed deliveries in a row to one endpoint, Xenarch emails you.

Every retry of a delivery carries the same `X-Xenarch-Delivery` id. Use it to ignore duplicates. List recent attempts with `xenarch links webhook deliveries <link_id>` and queue one again with `xenarch links webhook retry <link_id> <delivery_id>`.

Agent webhooks, configured for an agent rather than a pay link, use the same signature scheme and the same `verify` call.


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