Webhooks

Registering webhooks

To register a new webhook, you need to have a URL in your app that Vatly can call. You can configure a new webhook from the Vatly dashboard under API settings. Give your webhook a name, pick the events you want to listen for, and add your URL.

You can also manage the endpoint programmatically with the Webhook Endpoints API — handy for provisioning from CI / infrastructure-as-code or pointing an ephemeral preview environment at its own public URL. There is at most one endpoint per mode (test and live), and you supply the signing secret when you register it.

Now, whenever something of interest happens in your app, a webhook is fired off by Vatly. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

Each delivery is an HTTP POST whose body is a webhook_event object — the same shape returned by the Get webhook event endpoint. Check eventName to see what happened, and use entityType / entityId (or the embedded object snapshot) to act on the affected resource.

{
  "id": "webhook_event_Qk8pRtSvWm2NjLhYcZaE",
  "resource": "webhook_event",
  "eventName": "order.paid",
  "entityType": "order",
  "entityId": "order_Hn5xWqVfKm8RjTgYbUcP",
  "testmode": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "object": {
    "id": "order_Hn5xWqVfKm8RjTgYbUcP",
    "resource": "order",
    "testmode": false,
    "status": "paid",
    "total": { "value": "29.99", "currency": "EUR" },
    "subtotal": { "value": "24.79", "currency": "EUR" }
  },
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/webhook-events/webhook_event_Qk8pRtSvWm2NjLhYcZaE",
      "type": "application/json"
    }
  }
}

Every request also carries two headers you should use:

Event types

The eventName field identifies what happened. The available events are:

Example: subscription.started

{
  "id": "webhook_event_b167W0AChY7Z0Amr",
  "resource": "webhook_event",
  "eventName": "subscription.started",
  "entityType": "subscription",
  "entityId": "subscription_QdEpFhdSrG4Y3DnfsdqsH",
  "testmode": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "object": {
    "id": "subscription_QdEpFhdSrG4Y3DnfsdqsH",
    "resource": "subscription",
    "customerId": "customer_Bm7xNvPwKr3YjTgHcZaE",
    "subscriptionPlanId": "subscription_plan_Rk5pQrSvWm8NjLhYbUcP",
    "testmode": false,
    "name": "Premium Plan",
    "status": "active",
    "basePrice": { "value": "99.99", "currency": "EUR" },
    "quantity": 1,
    "interval": "month",
    "intervalCount": 1,
    "startedAt": "2024-01-15T10:30:00Z",
    "nextRenewalAt": "2024-02-15T10:30:00Z",
    "links": {
      "self": {
        "href": "https://api.vatly.com/v1/subscriptions/subscription_QdEpFhdSrG4Y3DnfsdqsH",
        "type": "application/json"
      },
      "customer": {
        "href": "https://api.vatly.com/v1/customers/customer_Bm7xNvPwKr3YjTgHcZaE",
        "type": "application/json"
      }
    }
  },
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/webhook-events/webhook_event_b167W0AChY7Z0Amr",
      "type": "application/json"
    }
  }
}

Handling failed subscription payments

When a subscription renewal payment fails, Vatly runs an automated payment recovery process (dunning) on your behalf. You never have to schedule your own retries — but you do decide when to restrict access.

Here is what happens, and what you receive:

1. The renewal payment fails and recovery begins. You receive a single order.payment_failed webhook for the renewal order — sent once, when recovery starts, not on each retry. The subscription's status stays active throughout recovery: it does not move to a "past due" state, and on_grace_period is never used for payment failure — that status means a voluntary cancellation that keeps access until the period ends.
2. Vatly attempts to recover the payment, and how it does so depends on why the charge failed:
   • Soft decline (e.g. insufficient funds, a temporary decline): the payment method is still valid, so Vatly automatically re-attempts the charge over a multi-week window, emailing the customer along the way.
   • Hard decline (e.g. an expired, canceled, or invalid payment method): retrying cannot succeed, so Vatly instead prompts the customer to supply a new payment method, on a shorter window.
3. If recovery succeeds, the original renewal order is paid and you receive order.paid for that same order. Because the subscription was never interrupted, access simply continues — nothing else is needed.
4. If recovery is exhausted (the customer never resolves it), Vatly cancels the subscription: you receive subscription.canceled_for_nonpayment and the subscription status becomes canceled with cancellationReason: payment_failure.

Recommended integration

Gate access on the events, not on a timer you keep in sync with ours:

• On order.payment_failed: keep access on, and start your own grace period if your product has one.
• On order.paid for the same order: recovery succeeded — clear that grace period.
• If your grace period elapses with no matching order.paid: restrict access on your side if you wish. Vatly's recovery keeps running underneath, so a later order.paid lets you restore access automatically.
• On the subscription's cancellation: remove access permanently.

Inspecting webhooks

To make integrating Vatly as smooth as possible, you can inspect a detailed webhook history in your Vatly dashboard.

If you store the event ID from a webhook delivery, you can also retrieve the full stored event later via the API:

• Get webhook event

That endpoint returns the event metadata plus the exact resource snapshot that was delivered at the time.

Testing webhook flows

For recurring billing flows, Vatly also exposes a test helper so you can trigger webhook-producing scenarios in test mode:

• Fast-forward subscription renewal

This is useful when you want to verify renewals and the events they produce without waiting for real billing dates.

Verifying signatures

To know for sure that a webhook was sent by Vatly and not a malicious actor, verify the signature on every delivery. Vatly signs each request with the Vatly-Signature header, which has the structured form:

Vatly-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>

• t is the Unix timestamp (in seconds) when the signature was generated.
• v1 is HMAC-SHA256("{t}.{rawBody}", yourWebhookSecret), hex-encoded — the timestamp and a literal . prepended to the exact raw request body.

To verify a delivery:

1. Parse t and v1 out of the header.
2. Reject the request if t is more than 300 seconds (5 minutes) from your server's current time — this guards against replay.
3. Recompute the HMAC over "{t}.{rawBody}" using your webhook secret and the raw request body bytes (not a re-serialized copy — re-encoding JSON changes the bytes and breaks the signature).
4. Compare your value against v1 using a constant-time comparison.

To verify it yourself:

import crypto from 'node:crypto'

// `rawBody` must be the exact bytes Vatly sent (e.g. express.raw()), not a parsed object.
function verifyVatlySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))
  const timestamp = Number(parts.t)
  const signature = parts.v1
  if (!timestamp || !signature) throw new Error('Malformed Vatly-Signature header')

  // Replay protection
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) {
    throw new Error('Signature timestamp outside tolerance window')
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    throw new Error('Invalid Vatly signature')
  }
}

import hashlib
import hmac
import time

def verify_vatly_signature(raw_body: str, header: str, secret: str, tolerance_seconds: int = 300) -> None:
    parts = dict(part.split("=", 1) for part in header.split(","))
    timestamp, signature = parts.get("t"), parts.get("v1")
    if not timestamp or not signature:
        raise ValueError("Malformed Vatly-Signature header")

    # Replay protection
    if abs(int(time.time()) - int(timestamp)) > tolerance_seconds:
        raise ValueError("Signature timestamp outside tolerance window")

    message = f"{timestamp}.{raw_body}".encode()
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError("Invalid Vatly signature")

$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_VATLY_SIGNATURE'] ?? '';
$toleranceSeconds = 300;

$parts = [];
foreach (explode(',', $header) as $part) {
    [$key, $value] = array_pad(explode('=', $part, 2), 2, null);
    $parts[trim((string) $key)] = trim((string) $value);
}
$timestamp = $parts['t'] ?? null;
$signature = $parts['v1'] ?? null;

if (! $timestamp || ! $signature || abs(time() - (int) $timestamp) > $toleranceSeconds) {
    http_response_code(400);
    exit('Invalid signature');
}

$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Request is verified
} else {
    http_response_code(400);
    exit('Invalid signature');
}

Keep your webhook secret safe and never commit it to source control. If it leaks, you can no longer trust that a given webhook was sent by Vatly.