---
title: "Register a notification webhook (free)"
method: POST
path: "/register-webhook"
tags: ["Notifications"]
---

# Register a notification webhook (free)

`POST /register-webhook`

## Request

- Base URL: `https://laso.finance`
- URL: `https://laso.finance/register-webhook`
- Auth: API key in header `Authorization`

Registers (or replaces) an HTTPS webhook URL to receive the calling wallet's account notifications as signed POSTs — banking application status changes, bank transfer and payout completions, agent wallet deposits, card orders, and every other event the user is notified about. This closes the polling gap for agents: instead of re-fetching status endpoints, point this at any URL you can receive HTTP on (your harness's inbound webhook endpoint, or a relay you poll).

Deliveries are signed per the Standard Webhooks specification (https://www.standardwebhooks.com/): each POST carries `webhook-id`, `webhook-timestamp`, and `webhook-signature` (`v1,<base64 HMAC-SHA256>`) headers verifiable with any standard-webhooks library using the returned `secret`. The body is `{"type": "notification.<category>", "timestamp": "<ISO 8601>", "data": {"user_id", "title", "text", "category"}}`.

The `secret` is returned exactly once, by this call. Re-registering rotates the secret, replaces the URL, and re-enables a registration that was auto-disabled after 50 consecutive failed deliveries. Registering also notifies the account owner through their other channels and fires a first signed test delivery (`type` `notification.account`) at the new URL.

Deliveries time out after 10 seconds and are not retried; treat the webhook as a low-latency hint and the status endpoints as the source of truth. The URL must be public HTTPS.

Requires a Bearer token from `/auth` or `/get-card`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, required: Public HTTPS URL to receive signed notification POSTs. Max 512 characters. Private/internal hosts are rejected.

## Response `200`

Webhook registered

- object
  - `registered` boolean
  - `url` string
  - `secret` string: Standard Webhooks signing secret (`whsec_...`). Shown only in this response — store it now. Rotate by re-registering.
  - `signing` string: Always `standard-webhooks`.

## Other responses

- `400`: Missing or invalid `url` (not HTTPS, not public, too long, or malformed)
- `401`: Missing or invalid Bearer token
- `403`: Account is frozen. The response includes a `frozen_message` field explaining why.
- `409`: A request with this `Idempotency-Key` is still being processed (`code: idempotency_key_in_progress`). Wait a moment and retry with the same key.
- `422`: The `Idempotency-Key` was already used for a different request body or route (`code: idempotency_key_reused`). Use a new key.

---

[API](https://skmtc.dev/laso/apis/laso-finance-x402-api.md) · [All operations](https://skmtc.dev/laso/apis/laso-finance-x402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/laso/apis/laso-finance-x402-api/revisions/ff8ce20b49ba?raw)