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
2. Go to Settings → API keys
3. Copy your TEST key

Store it as an environment variable rather than hardcoding it:

$
export SOLVIMON_API_KEY=your_test_key_here

Then use it in curl:

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

🚧 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 to create a tunnel during development.

1. Start ngrok

$
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 to register your local URL:

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

To receive all events, omit included_actions.

3. Verify it’s registered

Use GET /v1/webhooks:

$
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

$
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 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}:

$
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.