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"
    }
  }
}

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.