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

> ## Agent Instructions
> SolvaPay quick facts:
> - REST API base URL: https://api.solvapay.com. All public endpoints are under /v1/sdk/ (for example GET https://api.solvapay.com/v1/sdk/products). Sandbox and production share this URL.
> - Auth: send a secret key as `Authorization: Bearer <secret key>` (the REST API also accepts `X-API-Key: <secret key>`).
> - Secret key prefixes: `sk_sandbox_` (sandbox, test payments) and `sk_live_` (production). The prefix selects the environment.
> - Get keys in SolvaPay Console (https://app.solvapay.com) > Developers > API Keys. Use a sandbox key while building.
> - Admin MCP Server: https://mcp.solvapay.com/mcp (Streamable HTTP). Connect with OAuth: add the URL and sign in with the SolvaPay account; no API key needed. OAuth sessions use the live account; for sandbox data or headless clients, send `Authorization: Bearer <secret key>` (X-API-Key is ignored).
> - Install the SolvaPay agent skills: `npx skills add https://solvapay.com` (skills CLI older than 1.5.7: `npx skills add solvapay/skills`).
> - TypeScript SDK setup: `npx solvapay@latest init`. The SDK reads SOLVAPAY_SECRET_KEY and defaults to https://api.solvapay.com.
> - Plans take an options[] array (billingCycle, charge, limit, ...). Retired plan fields price, freeUnits and billingCycle are rejected.
> - Step-by-step from zero to a first paid call: Managed MCP https://docs.solvapay.com/build/managed-mcp.md, TypeScript SDK https://docs.solvapay.com/build/typescript-sdk.md, agent skill https://docs.solvapay.com/build/agent-skill.md.
> - Details: https://docs.solvapay.com/api-reference/authentication.md. OpenAPI spec: https://docs.solvapay.com/api-reference/openapi.json.

# Webhooks

> Verify SolvaPay webhooks in Python with verify_webhook and handle the events.

`verify_webhook` checks a delivery's `sv-signature` header and returns the parsed event. For the event catalog, payloads and how to set up an endpoint, see the [Webhooks documentation](https://docs.solvapay.com/webhooks.md).

## Prerequisites

* A webhook endpoint in SolvaPay Console, and its signing secret (`whsec_...`) in `SOLVAPAY_WEBHOOK_SECRET`.

## Add a receiver route

```python theme={null}
import os

from solvapay import SolvaPayError, verify_webhook
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse, Response
from starlette.routing import Route

WEBHOOK_SECRET = os.environ["SOLVAPAY_WEBHOOK_SECRET"]


async def solvapay_webhook(request: Request) -> Response:
    try:
        event = verify_webhook(
            body=await request.body(),  # the raw bytes, before any JSON parsing
            signature=request.headers.get("sv-signature"),
            secret=WEBHOOK_SECRET,
        )
    except SolvaPayError as error:
        return JSONResponse({"error": error.code}, status_code=401)

    if event["type"] == "purchase.created":
        ...  # grant access
    elif event["type"] == "purchase.cancelled":
        ...  # revoke access
    return Response(status_code=200)


app = Starlette(routes=[Route("/webhooks/solvapay", solvapay_webhook, methods=["POST"])])
```

Pass the body exactly as received, as `bytes` or `str`. The signature covers the raw bytes, so a body you parsed and serialized again fails the check. In FastAPI, read it with `await request.body()` too.

The event is a plain dict parsed from the JSON body.

## How the signature is checked

The `sv-signature` header looks like `t=1767225600,v1=5f3c...`. `verify_webhook` computes an HMAC-SHA256 over `"{t}.{raw body}"` with your signing secret and compares it to `v1` in constant time. A timestamp more than 300 seconds from now, in either direction, is rejected. Pass `now=` (a `datetime`) to check against another time, for example in tests.

## Error codes

`verify_webhook` raises `SolvaPayError` with one of these codes, also in `WEBHOOK_ERROR_CODES`:

| Code | Cause |
| - | - |
| `webhook_secret_missing` | `secret` is empty: checked first, so every delivery fails until it's set |
| `webhook_signature_missing` | No `sv-signature` header |
| `webhook_signature_malformed` | The header has no `t=` or `v1=` part, or the timestamp isn't a number |
| `webhook_timestamp_out_of_tolerance` | The timestamp is more than 300 seconds from now |
| `webhook_signature_invalid` | The signature doesn't match: wrong secret, or a changed body |
| `webhook_payload_invalid` | The signature matches, but the body isn't valid JSON |

Answer a failed check with a `4xx`, so the delivery shows as failed in SolvaPay Console.

## Next steps

* The TypeScript equivalent is [webhook handling](https://docs.solvapay.com/sdks/typescript/guides/webhooks.md).


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