Vorgio

Webhooks

Vorgio POSTs JSON events to your endpoint when invoices change state. Your shop uses these events to fulfil orders, reconcile payments, and surface status to the merchant.

#Setup

In your Vorgio team settings, open Webhooks. Each team can register multiple endpoints; each endpoint subscribes to a subset of event types.

For each endpoint you provide:

  • URL — must be https://. Vorgio refuses plain HTTP.
  • Events — pick from the catalogue below. You can update this later.

After creating the endpoint Vorgio shows the signing secret once. Copy it — you cannot view it again. If you lose it, or it leaks, click Rotate secret on the endpoint's row: Vorgio shows a new secret once and keeps signing with the previous one for 24 hours, so your receiver keeps working while you swap it in. The endpoint, its URL and its events stay as they are. See Rotating the signing secret below.

#Receiving the request: framework caveats

Vorgio's webhook POSTs are cross-origin and session-less — there's no cookie, no CSRF token, no _token field. If your framework enables CSRF protection by default for POST requests (Laravel, Django, Rails, ASP.NET MVC, …) the request is rejected with a 419/403 HTML error page before your handler ever runs. Vorgio records this as a failed delivery and retries — your 2xx-returning handler is never reached.

The robust fix is to register the webhook route in a route group that has no session / CSRF middleware in the first place. Per-route exemptions work too, but they leak the gotcha into every place the route is registered. Concrete recipes:

Laravel 11/12/13 — preferred: dedicated routes/api.php. The api group has no session and no CSRF. In bootstrap/app.php:

 1->withRouting(
 2    web: __DIR__.'/../routes/web.php',
 3    api: __DIR__.'/../routes/api.php',
 4    commands: __DIR__.'/../routes/console.php',
 5    health: '/up',
 6)

Then in routes/api.php:

 1use App\Http\Controllers\Webhooks\VorgioWebhookController;
 2use Illuminate\Support\Facades\Route;
 3
 4Route::post('/webhooks/vorgio', VorgioWebhookController::class)
 5    ->name('webhooks.vorgio');

The default apiPrefix is api, so the URL becomes https://your-shop.example/api/webhooks/vorgio — register that URL on vorgio.app's Webhooks page. Pass apiPrefix: '' to withRouting if you want the route at the bare /webhooks/vorgio path.

Laravel — alternative: keep the route in routes/web.php and exempt it from CSRF. Inside the withMiddleware block in bootstrap/app.php:

 1$middleware->preventRequestForgery(except: [
 2    'webhooks/vorgio',
 3]);

(Older docs still call this validateCsrfTokens — that method is deprecated in Laravel 13 in favour of preventRequestForgery. Same behaviour, renamed.)

Django — decorate the view with @csrf_exempt:

 1from django.views.decorators.csrf import csrf_exempt
 2
 3@csrf_exempt
 4def vorgio_webhook(request): ...

Rails — skip the authenticity-token check on the controller action:

 1class VorgioWebhooksController < ApplicationController
 2  skip_before_action :verify_authenticity_token, only: :create
 3end

ASP.NET MVC — [IgnoreAntiforgeryToken] on the action.

If your Vorgio webhook delivery log shows response_status: 419 (Laravel), 403 with a Django error page, or any HTML body where you expected to see your own response, this is almost always the cause.

#Event catalogue (v1)

type When it fires Typical use
invoice.sent After an invoice email has been queued for delivery — i.e. immediately after a successful POST /v1/checkouts (or after the merchant clicks "Send" in the Vorgio UI). Move the shop order to on-hold or processing depending on your fulfilment policy.
invoice.paid When the merchant marks the invoice as paid (in the Vorgio UI, or via POST /v1/invoices/{id}/mark-paid). Move the shop order to processing (or completed) and reconcile your books.

The catalogue is additive over time. New event types ship as opt-in subscriptions; existing event names are not renamed.

#Payload shape

 1{
 2  "id": "evt_01HX9F2K7N8R5SQT3WYPJ4M6V0",
 3  "type": "invoice.sent",
 4  "created_at": "2026-05-10T12:34:56+00:00",
 5  "data": {
 6    "invoice": { /* full InvoiceResource — same shape as GET /v1/invoices/{id} */ },
 7    "client":  { /* full ClientResource — same shape as GET /v1/clients/{id}  */ }
 8  },
 9  "metadata": {
10    "shop_order_id": "1234"      // exactly what you sent on the original POST /v1/checkouts
11  }
12}

The metadata echo is the recommended way to correlate events back to your shop's records. See Metadata for patterns.

#Signature verification (mandatory)

Every request carries a Vorgio-Signature header:

 1Vorgio-Signature: t=1715342400,v1=4f8d2c...hex...
 2Vorgio-Event: invoice.sent

The v1 value is HMAC-SHA256 over <timestamp>.<raw_request_body> using your endpoint's signing secret as the key. The scheme is intentionally identical to Stripe's, so any of the dozens of "Stripe webhook verify" snippets on the internet will work after a global find-and-replace from Stripe-Signature to Vorgio-Signature.

Always verify before trusting the payload. An attacker who knows your URL but not your secret cannot forge a valid signature.

Accept any matching v1. For 24 hours after a secret rotation the header carries two v1 values, one per secret, newest first:

 1Vorgio-Signature: t=1715342400,v1=<signature with the new secret>,v1=<signature with the previous secret>

Your receiver holds one secret. Parse every v1 value, compare each one against the signature you compute, and accept the request if any of them matches. A verifier that expects exactly one v1 rejects every delivery during the grace period. The snippets below, the PHP SDK and the WooCommerce plugin all accept any matching v1.

#PHP

 1function vorgioVerify(string $payload, string $sigHeader, string $secret, int $tolerance = 300): array
 2{
 3    $ts = null;
 4    $signatures = [];
 5    foreach (explode(',', $sigHeader) as $part) {
 6        [$key, $value] = array_pad(explode('=', $part, 2), 2, '');
 7        if ($key === 't' && ctype_digit($value)) {
 8            $ts = $value;
 9        } elseif ($key === 'v1' && $value !== '') {
10            $signatures[] = $value;
11        }
12    }
13    if ($ts === null || $signatures === []) {
14        throw new RuntimeException('Malformed Vorgio-Signature');
15    }
16
17    if (abs(time() - (int) $ts) > $tolerance) {
18        throw new RuntimeException('Stale Vorgio-Signature');
19    }
20
21    // Compare every candidate in constant time; do not stop at the first match.
22    $expected = hash_hmac('sha256', $ts . '.' . $payload, $secret);
23    $matched = false;
24    foreach ($signatures as $signature) {
25        $matched = hash_equals($expected, $signature) || $matched;
26    }
27    if (! $matched) {
28        throw new RuntimeException('Invalid Vorgio-Signature');
29    }
30
31    return json_decode($payload, true, flags: JSON_THROW_ON_ERROR);
32}
33
34// In your endpoint:
35$event = vorgioVerify(
36    file_get_contents('php://input'),
37    $_SERVER['HTTP_VORGIO_SIGNATURE'] ?? '',
38    getenv('VORGIO_WEBHOOK_SECRET'),
39);

#Node.js

 1import { createHmac, timingSafeEqual } from 'node:crypto';
 2
 3export function vorgioVerify(rawBody: string, sigHeader: string, secret: string, toleranceSec = 300) {
 4  let ts: string | undefined;
 5  const signatures: string[] = [];
 6  for (const part of sigHeader.split(',')) {
 7    const [key, ...rest] = part.split('=');
 8    const value = rest.join('=');
 9    if (key === 't' && /^\d+$/.test(value)) ts = value;
10    else if (key === 'v1' && value !== '') signatures.push(value);
11  }
12  if (ts === undefined || signatures.length === 0) throw new Error('Malformed Vorgio-Signature');
13
14  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) {
15    throw new Error('Stale Vorgio-Signature');
16  }
17  // Compare every candidate in constant time; do not stop at the first match.
18  const expected = Buffer.from(createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex'));
19  let matched = false;
20  for (const signature of signatures) {
21    const candidate = Buffer.from(signature);
22    if (candidate.length === expected.length && timingSafeEqual(candidate, expected)) matched = true;
23  }
24  if (!matched) {
25    throw new Error('Invalid Vorgio-Signature');
26  }
27  return JSON.parse(rawBody);
28}

#Python

 1import hashlib, hmac, json, time
 2
 3def vorgio_verify(raw_body: bytes, sig_header: str, secret: str, tolerance: int = 300) -> dict:
 4    ts, signatures = None, []
 5    for part in sig_header.split(","):
 6        key, _, value = part.partition("=")
 7        if key == "t" and value.isascii() and value.isdigit():
 8            ts = value
 9        elif key == "v1" and value:
10            signatures.append(value.encode())
11    if ts is None or not signatures:
12        raise ValueError("Malformed Vorgio-Signature")
13    if abs(time.time() - int(ts)) > tolerance:
14        raise ValueError("Stale Vorgio-Signature")
15    # Compare every candidate in constant time; do not stop at the first match.
16    expected = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest().encode()
17    matched = False
18    for signature in signatures:
19        matched = hmac.compare_digest(expected, signature) or matched
20    if not matched:
21        raise ValueError("Invalid Vorgio-Signature")
22    return json.loads(raw_body)

#Rotating the signing secret

Rotate an endpoint's secret when it is lost or may have leaked, or simply on a schedule.

  1. On the Webhooks page, click Rotate secret on the endpoint's row and confirm.
  2. Vorgio shows the new secret once. Copy it, then click Done. The endpoint keeps its id, URL, events and delivery history.
  3. Put the new secret into your receiver within 24 hours.

For 24 hours after the rotation, every delivery and every connection test is signed with both secrets: two v1 values, the new one first. A receiver that still holds the previous secret verifies, and so does one that already holds the new secret, so the receiver keeps working whether you swap in the new secret right away or later within the 24 hours. After 24 hours Vorgio signs with the new secret alone, and the header has one v1 again.

  • Rotating again during the 24 hours drops the oldest secret at once. Vorgio never sends more than two signatures, so a receiver still on the secret from two rotations ago stops verifying immediately.
  • The 24 hours cannot be shortened. If the old secret leaked, update your receiver straight away: it checks against the one secret it holds, so once it holds the new one, a request signed with the leaked secret no longer verifies.
  • Live and test mode are separate. Each endpoint has its own secret; rotating a test-mode endpoint leaves the live ones untouched, and vice versa.

#Delivery semantics

  • At-least-once. Your endpoint may receive the same event twice (rarely). Be idempotent on the event.id if you do anything irreversible (e.g. shipping the order).
  • Initial attempt is immediate. Vorgio dispatches the webhook job immediately after the in-app event fires.
  • Retries on 4xx (≥ 400) or 5xx response, or any network error. Retry schedule:
    • Attempt 2: 1 minute after the first
    • Attempt 3: 5 minutes
    • Attempt 4: 30 minutes
    • Attempt 5: 2 hours
    • Attempt 6: 12 hours
    • Attempt 7: 24 hours
  • After the 7th failed attempt (~ 2 days total), Vorgio automatically disables the endpoint and surfaces a banner in the team's Webhooks UI. The merchant must manually re-enable it after fixing the receiver. No further events are queued for a disabled endpoint.

Respond with 2xx within 30 seconds (the timeout). Anything else is treated as a failure and triggers a retry.

#Best practices

  • Be fast. Acknowledge with 200 OK immediately, then process asynchronously (queue, background job). A slow handler eats into Vorgio's 30-second timeout and risks duplicate deliveries.
  • Verify the signature before parsing the JSON body — the verifier needs the raw bytes.
  • Handle out-of-order arrival. Rarely, attempt 2 of event A can arrive after event B. Use event.id for idempotency and created_at for ordering decisions.
  • Don't trust the Host or User-Agent headers for authentication — only the signature.
  • Use a separate webhook endpoint per environment (dev / staging / prod). Each gets its own secret.

#Testing

For a quick test you can replay a real event from your team's Webhooks UI: open the endpoint detail page → recent deliveries → click "Replay". The same payload is re-POSTed with a fresh signature timestamp.

For full end-to-end testing — generating real (but suppressed) invoices that fire real webhooks to a separate set of test endpoints — use Test mode. Test-mode invoices fire only to test webhooks; live-mode invoices fire only to live webhooks. The HTTP request, payload, and signature scheme are byte-identical between modes.