Vorgio

Verifying your connection

Most failed integrations fail for boring reasons: a test token in production, a token missing an ability, or a webhook registered at the wrong URL (or with the wrong secret). These are all things only Vorgio can confirm authoritatively — so Vorgio exposes a small introspection surface, and the PHP SDK turns it into a one-command checklist.

Requires the PHP SDK ≥ 0.3.0 and a Vorgio instance that exposes the /v1/connection endpoints. See PHP SDK to install.

#The doctor command (recommended)

If you're on Laravel, run:

 1php artisan vorgio:doctor
 1✓ API token — VORGIO_TOKEN is set.
 2✓ Reachable & authenticated — Vorgio accepted the token.
 3✓ Mode — Token is in LIVE mode.
 4✓ Token abilities — All required abilities are granted.
 5✓ Webhook — Active webhook registered for https://your-shop.example/webhooks/vorgio with the required events.
 6✓ Mirror tables — All Vorgio mirror tables exist.
 7
 8Team: your-team  Mode: live
 9
10Vorgio connection looks good.

Each line is a pass (✓), warning (!) or failure (✗). The command exits non-zero if any check fails, so you can wire it into your deploy pipeline as a gate.

Add --test-webhook to also have Vorgio deliver a signed connection.test event to your registered endpoint(s) and report whether each one accepted it:

 1php artisan vorgio:doctor --test-webhook
 1…
 2✓ Webhook delivery — Your endpoint received and verified a signed test event.

A green Webhook delivery line is the strongest signal available: it means your receiver verified the signature, which proves the shared secret and the endpoint URL line up end-to-end. (The introspection checks above can confirm a webhook is registered, but only a real delivery can confirm the secret.)

#What each check means

Check A failure (✗) means
API token VORGIO_TOKEN is empty. Nothing else can run.
Reachable & authenticated Vorgio is unreachable, or rejected the token (revoked / wrong value / wrong base_url).
Mode A warning (!), not a failure: the token is in test mode. Test invoices are not emailed and do not bill — use a live token in production.
Token abilities The token is missing one or more abilities your integration needs. Re-issue it with the matching preset.
Webhook No active webhook is registered for your app's URL, it's inactive (auto-disabled after repeated failures), or it's missing required events.
Mirror tables The SDK's vorgio_* tables are missing — run php artisan migrate.
Webhook delivery Your endpoint rejected the test event — wrong URL, unreachable, or VORGIO_WEBHOOK_SECRET doesn't match the registered webhook's secret.

#Rendering the report in your own UI

The command is a thin wrapper over Vorgio\Laravel\ConnectionDoctor, which you can call directly — e.g. to show a connection panel on an operator settings page:

 1use Vorgio\Laravel\ConnectionDoctor;
 2
 3$report = app(ConnectionDoctor::class)->run();              // introspection only — cheap, no side effects
 4// $report = app(ConnectionDoctor::class)->run(includeWebhookTest: true); // also fires a live test event
 5
 6if (! $report['ok']) {
 7    // surface the failing checks to the operator
 8}
 9
10foreach ($report['checks'] as $check) {
11    // $check = ['key' => 'webhook', 'label' => 'Webhook', 'status' => 'ok|warn|fail', 'detail' => '…']
12}
13
14$report['connection']; // the raw payload: team, mode, token abilities, registered webhooks

Keep includeWebhookTest off for anything that renders on every request — it performs a real outbound delivery. Trigger it from an explicit "send test webhook" button instead.

#Tuning what "correct" means

The doctor's expectations live in config/vorgio.php. Trim them to match what your integration actually uses:

 1'required_abilities' => [
 2    'clients:write', 'invoices:write', 'invoices:send',
 3    'invoices:read', 'checkouts:write', 'webhooks:manage',
 4],
 5
 6'required_webhook_events' => ['invoice.sent', 'invoice.paid'],

The defaults match the recurring-billing preset. A one-shot shop that never registers clients or sends invoices itself can drop the abilities it doesn't use.

#Without the PHP SDK

The doctor is just a client of two endpoints — call them directly from any language:

  • GET /v1/connection — returns the authenticated token's team, mode, abilities, billing readiness and the webhooks registered for its team + mode:

     1{
     2  "data": {
     3    "team": { "slug": "your-team", "name": "Your Team" },
     4    "mode": "live",
     5    "token": { "name": "Acme Shop production", "abilities": ["checkouts:write", "…"] },
     6    "billing": { "has_iban": true },
     7    "webhooks": [
     8      { "url": "https://your-shop.example/webhooks/vorgio", "events": ["invoice.sent", "invoice.paid"], "active": true }
     9    ]
    10  }
    11}
    

    Any valid token may call this — no specific ability required.

  • POST /v1/connection/test-webhook — delivers a signed connection.test event to every active webhook for the token's team + mode and returns a per-endpoint result. Requires the webhooks:manage ability.

     1{ "data": { "results": [ { "url": "https://your-shop.example/webhooks/vorgio", "ok": true, "status": 200, "error": null } ] } }
    

connection.test is a no-op event for receivers — your webhook handler should verify the signature (which is the whole point of the test) and return 2xx without acting on it. The signature scheme is identical to every other event; see Webhooks.

#What it can't tell you

  • It can't see outbound problems where your endpoint silently swallows events — that's what the going-live monitoring checklist is for.
  • A green report means configuration is correct, not that a real invoice round-trip works. Always finish with the going-live smoke test against a real (small) order.