> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Local development setup

How to configure your local environment to make API calls and receive webhooks from Solvimon during development.

---

## Sandbox credentials

Sandbox API keys are available immediately — no contract required.

1. Log in to [test.desk.solvimon.com](https://test.desk.solvimon.com)
2. Go to **Developers → API keys** and click **Add API key**
3. Enter a **Description**, click **Generate** and copy the key. You cannot view it again after you close the dialog.

Store it as an environment variable rather than hardcoding it:

```bash
export SOLVIMON_API_KEY=your_test_key_here
```

Then use it in curl:

```bash
curl https://test.api.solvimon.com/v1/customers \
  -H "X-API-KEY: $SOLVIMON_API_KEY"
```

> **Warning**
>
> Test keys only work against `test.api.solvimon.com`. Using a test key against `api.solvimon.com` returns `401`.

---

## Receiving webhooks locally

Solvimon needs a publicly reachable HTTPS URL to deliver webhooks. Since `localhost` isn't reachable externally, use [ngrok](https://ngrok.com) to create a tunnel during development.

### 1. Start ngrok

```bash
ngrok http 3000
```

ngrok prints a forwarding URL like `https://a1b2c3d4.ngrok.io`. Copy it.

### 2. Register the webhook endpoint with Solvimon

Use [POST /v1/webhooks](https://docs.solvimon.com/api-docs/configuration-api/webhooks/post-webhooks) to register your local URL:

```bash
curl -X POST https://test.api.solvimon.com/v1/webhooks \
  -H "X-API-KEY: $SOLVIMON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local development",
    "reference": "local-dev",
    "url": "https://a1b2c3d4.ngrok.io/webhooks/solvimon",
    "included_actions": [
      "INVOICE.STATUS_TO_FINAL",
      "PAYMENT.CREATED",
      "CUSTOMER.CREATED"
    ]
  }'
```

To receive all events, omit `included_actions`.

### 3. Verify it's registered

Use [GET /v1/webhooks](https://docs.solvimon.com/api-docs/configuration-api/webhooks/get-webhooks):

```bash
curl https://test.api.solvimon.com/v1/webhooks \
  -H "X-API-KEY: $SOLVIMON_API_KEY"
```

You should see your endpoint listed with `status: "ACTIVE"`.

---

## Recommended environment variables

```bash
export SOLVIMON_API_KEY=your_test_key_here
export SOLVIMON_WEBHOOK_SECRET=your_webhook_signing_secret
export SOLVIMON_ENV=test
```

The webhook signing secret is shown once when you create the webhook endpoint. Use it to verify the `X-SOLVIMON-SIGNATURE` header on incoming events — see the [Webhooks guide](/platform-guides/for-developers/webhooks) for the verification steps.

---

## Common issues

**ngrok tunnel expired** — Free ngrok tunnels expire after a few hours. If webhooks stop arriving, run `ngrok http 3000` again to get a new URL, then update the registration via [PATCH /v1/webhooks/\{id}](https://docs.solvimon.com/api-docs/configuration-api/webhooks/patch-webhooks-by-resource-id):

```bash
curl -X PATCH https://test.api.solvimon.com/v1/webhooks/<webhook_id> \
  -H "X-API-KEY: $SOLVIMON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://new-url.ngrok.io/webhooks/solvimon"}'
```

**Webhook not arriving** — Your handler must return a `2XX` status within 10 seconds. If it returns anything else (or times out), Solvimon queues the event for retry and holds subsequent webhooks until the queue clears. Check your server logs for errors before the response is sent.

**`401 Unauthorized`** — Confirm you're using a test key (prefixed `TEST_`) against `test.api.solvimon.com`, not the production endpoint.