> ## 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

> Receive SolvaPay webhook events in Go and verify their signatures.

SolvaPay sends a signed JSON event to your endpoint when something happens, such as a purchase being created or a payment succeeding. `VerifyWebhook` checks the signature and parses the event. For the event catalogue and payload shapes, see [Webhooks](https://docs.solvapay.com/webhooks.md).

## Prerequisites

1. In SolvaPay Console, go to **Settings** > **Webhooks** and add your endpoint URL.
2. Copy the signing secret (`whsec_…`) into `SOLVAPAY_WEBHOOK_SECRET`.

## Receive events

```go main.go theme={null}
package main

import (
	"io"
	"log"
	"net/http"
	"os"
	"time"

	solvapay "github.com/solvapay/solvapay-sdk/go"
)

func main() {
	secret := os.Getenv("SOLVAPAY_WEBHOOK_SECRET") // whsec_...
	if secret == "" {
		log.Fatal("SOLVAPAY_WEBHOOK_SECRET is not set")
	}

	http.HandleFunc("POST /webhooks/solvapay", func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(r.Body) // the raw bytes, before any JSON decoding
		if err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		event, err := solvapay.VerifyWebhook(body, r.Header.Get("SV-Signature"), secret, time.Time{})
		if err != nil {
			log.Printf("rejected webhook: %s", solvapay.ErrorCode(err))
			http.Error(w, "invalid signature", http.StatusUnauthorized)
			return
		}

		fields, _ := event.(map[string]any)
		switch fields["type"] {
		case "purchase.created":
			// grant access
		case "purchase.cancelled":
			// revoke access
		case "payment.succeeded":
			// fulfil the order
		}
		w.WriteHeader(http.StatusOK)
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

`VerifyWebhook(body, signature, secret, now)` takes:

* `body`: the request body exactly as received. Read it with `io.ReadAll` before anything decodes it. If the body is decoded and encoded again, the signature check fails.
* `signature`: the `SV-Signature` header, `t=<unix seconds>,v1=<hex HMAC>`.
* `secret`: the whole signing secret, including `whsec_`.
* `now`: the time to check the timestamp against. The zero `time.Time` means the current time.

It returns the event as decoded JSON (`map[string]any`, with numbers as `json.Number`). Return a `2xx` once you have handled it.

## Errors

A failed check returns a `*solvapay.Error` with one of these codes:

| Code | Meaning |
| - | - |
| `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 |
| `webhook_timestamp_out_of_tolerance` | The timestamp is more than 300 seconds from `now` |
| `webhook_signature_invalid` | The signature does not match the body and secret |
| `webhook_payload_invalid` | The body is not valid JSON |

The codes are constants too: `solvapay.WebhookSecretMissing`, `WebhookSignatureMissing`, `WebhookSignatureMalformed`, `WebhookTimestampOutOfRange`, `WebhookSignatureInvalid` and `WebhookPayloadInvalid`.

> [!WARNING]
>
> `VerifyWebhook` does not check that `secret` is set. With an empty secret, anyone can sign an event that verifies. Check the secret at startup, as the example does.

## Next steps

* [Webhooks](https://docs.solvapay.com/webhooks.md): every event type and its payload.
* The TypeScript equivalent of this page: [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.