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

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"

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 '{
    "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:

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.