> For the complete documentation index, see [llms.txt](https://noiho.gitbook.io/noiho/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://noiho.gitbook.io/noiho/developers/api-consumers/webhooks-and-security.md).

# Signed webhooks and integration security

Verify durable webhook events and keep partner credentials on your backend.

Webhooks need operator-provisioned partner configuration and an HTTPS destination. Requests cannot choose their own webhook URL. Check capabilities: the public deployment reported webhooks: false on October 10, 2026. Do not assume public wallet sessions enable webhooks.

Delivery is at least once. Deduplicate with JSON id or X-Noiho-Event-Id. Snapshots can arrive out of order; fetch current owned status before acting. Return 2xx only after durable receipt.

```
X-Noiho-Timestamp: <Unix seconds>
X-Noiho-Signature: v1=<hex>

HMAC-SHA256(webhook_secret, timestamp + "." + exact_raw_request_body)
```

Verify the signature with a constant-time comparison before parsing or changing the body. Reject timestamps outside your chosen tolerance, for example five minutes. Keep the webhook secret separate from the partner token.

Retries retain the same event ID and body with a fresh timestamp and signature. Exponential retries start at 10 seconds and cap at one hour. After ten failed deliveries, explicit replay is required.

POST /v1/orders/{id}/webhook/retry requeues exhausted delivery for an authorized order. It cannot resend a financial transaction. Redirects are not followed. Destinations must resolve to public IPv4 addresses; IPv6-only receivers are unsupported.

* Keep partner bearer tokens on the backend. Never put them in frontend bundles or logs.
* Keep wallet session tokens in memory. Logout when access is no longer needed.
* Do not collect wallet private keys or raw signed transactions.
* Do not treat a deposit address or public order ID as authorization.
* Do not use legacy /status, /resume, /permit or /permit-payload for integration-created orders.

Use capabilities for current network and feature availability. API support does not imply contract-wallet support or acceptance by an external aggregator.

Request partner provisioning and webhook setup through the operator. Do not include tokens, internal database locations or private probe identities in support reports.