Verbindung prüfen

Die meisten gescheiterten Integrationen scheitern aus banalen Gründen: ein Test-Token in der Produktion, ein Token, dem eine Ability fehlt, oder ein Webhook, der unter der falschen URL (oder mit dem falschen Secret) registriert ist. Das alles kann nur Vorgio verbindlich bestätigen — deshalb stellt Vorgio eine kleine Introspektions-Schnittstelle bereit, und das PHP-SDK macht daraus eine Ein-Befehl-Checkliste.

Erfordert das PHP-SDK ≥ 0.3.0 und eine Vorgio-Instanz mit den /v1/connection-Endpoints. Zur Installation siehe PHP-SDK.

#Der Doctor-Befehl (empfohlen)

Wenn Sie Laravel nutzen, führen Sie aus:

 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://ihr-shop.example/webhooks/vorgio with the required events.
 6✓ Mirror tables — All Vorgio mirror tables exist.
 7
 8Team: ihr-team  Mode: live
 9
10Vorgio connection looks good.

Jede Zeile ist ein Erfolg (✓), eine Warnung (!) oder ein Fehler (✗). Der Befehl endet mit Exit-Code ≠ 0, wenn ein Check fehlschlägt — so können Sie ihn als Gate in Ihre Deploy-Pipeline einbauen.

Mit --test-webhook lässt Vorgio zusätzlich ein signiertes connection.test-Event an Ihre registrierten Endpoints zustellen und meldet, ob jeder davon es akzeptiert hat:

 1php artisan vorgio:doctor --test-webhook

 1…
 2✓ Webhook delivery — Your endpoint received and verified a signed test event.

Eine grüne Webhook-delivery-Zeile ist das stärkste verfügbare Signal: Ihr Empfänger hat die Signatur verifiziert, was Secret und Endpoint-URL durchgängig bestätigt. (Die Introspektions-Checks oben können bestätigen, dass ein Webhook registriert ist — aber nur eine echte Zustellung bestätigt das Secret.)

#Was jeder Check bedeutet

#Den Report in der eigenen Oberfläche anzeigen

Der Befehl ist nur ein dünner Wrapper um Vorgio\Laravel\ConnectionDoctor, den Sie direkt aufrufen können — z. B. um ein Verbindungs-Panel auf einer Betreiber-Einstellungsseite anzuzeigen:

 1use Vorgio\Laravel\ConnectionDoctor;
 2
 3$report = app(ConnectionDoctor::class)->run();              // nur Introspektion — günstig, ohne Nebenwirkungen
 4// $report = app(ConnectionDoctor::class)->run(includeWebhookTest: true); // löst zusätzlich ein echtes Test-Event aus
 5
 6if (! $report['ok']) {
 7    // fehlgeschlagene Checks dem Betreiber anzeigen
 8}
 9
10foreach ($report['checks'] as $check) {
11    // $check = ['key' => 'webhook', 'label' => 'Webhook', 'status' => 'ok|warn|fail', 'detail' => '…']
12}
13
14$report['connection']; // die rohe Payload: Team, Modus, Token-Abilities, registrierte Webhooks

Lassen Sie includeWebhookTest ausgeschaltet für alles, was bei jedem Request rendert — es führt eine echte ausgehende Zustellung durch. Lösen Sie es stattdessen über einen expliziten „Test-Webhook senden"-Button aus.

#Festlegen, was „korrekt" bedeutet

Die Erwartungen des Doctors stehen in config/vorgio.php. Passen Sie sie an das an, was Ihre Integration tatsächlich nutzt:

 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'],

Die Defaults entsprechen dem recurring-billing-Preset. Ein One-Shot-Shop, der selbst keine Clients anlegt oder Rechnungen versendet, kann die nicht genutzten Abilities entfernen.

#Ohne das PHP-SDK

Der Doctor ist nur ein Client zweier Endpoints — rufen Sie sie aus jeder Sprache direkt auf:

• GET /v1/connection — liefert Team, Modus, Abilities, Abrechnungsbereitschaft und die für Team + Modus registrierten Webhooks des authentifizierten Tokens:

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

  Jedes gültige Token darf dies aufrufen — keine spezielle Ability erforderlich.

• POST /v1/connection/test-webhook — stellt ein signiertes connection.test-Event an jeden aktiven Webhook für Team + Modus des Tokens zu und liefert ein Ergebnis pro Endpoint. Erfordert die Ability webhooks:manage.

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

connection.test ist für Empfänger ein No-Op-Event — Ihr Webhook-Handler sollte die Signatur verifizieren (genau das ist der Sinn des Tests) und 2xx zurückgeben, ohne darauf zu reagieren. Das Signatur-Schema ist identisch zu allen anderen Events; siehe Webhooks.

#Was er nicht erkennen kann

• Er erkennt keine ausgehenden Probleme, bei denen Ihr Endpoint Events stillschweigend verschluckt — dafür ist die Monitoring-Checkliste unter Live gehen da.
• Ein grüner Report bedeutet, dass die Konfiguration korrekt ist — nicht, dass ein echter Rechnungs-Durchlauf funktioniert. Schließen Sie immer mit dem Smoke-Test aus „Live gehen" gegen eine echte (kleine) Bestellung ab.