Webhooks & events

Subscriptions and invoices move through their lifecycle asynchronously — trials end, renewals collect, payments fail and retry — so the source of truth for "what just happened" is the webhook stream, not your API call. This page covers the events VINR emits across that lifecycle and how to handle them idempotently so your system stays in sync.

Why events, not pollingAskCopy

A subscription is a long-lived object that changes on VINR's clock: the renewal at midnight, the dunning retry three days later, the SCA challenge the customer completes on their phone. None of these originate from a request you made, so polling can only ever tell you the current state — never reliably when it changed. Webhooks push each transition to you the moment it occurs, which is what lets you grant or revoke access in real time.

The lifecycle eventsAskCopy

The events below cover the common subscription and invoice transitions. Most integrations only need to handle a handful — the renewal, the failure, and the cancellation.

Verifying and routing the webhookAskCopy

Every delivery carries an x-vinr-signature header. Verify it against the raw request body before trusting anything — vinr.webhooks.verify throws if the signature is invalid or the timestamp is stale.

import { Vinr } from '@vinr/sdk';
import express from 'express';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });
const app = express();

// IMPORTANT: verify against the *raw* body, not parsed JSON.
app.post('/webhooks/vinr', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = vinr.webhooks.verify(
      req.body,                          // raw Buffer
      req.headers['x-vinr-signature'],
      process.env.VINR_WEBHOOK_SECRET,   // from the endpoint (we_...)
    );
  } catch {
    return res.status(400).send('invalid signature');
  }

  // Acknowledge fast; do real work async (see idempotency below).
  enqueue(event);
  res.status(200).send('ok');
});

Handling events idempotentlyAskCopy

VINR guarantees at-least-once delivery, so the same event can arrive more than once (a slow ACK, a retry, a network blip). Deduplicate on event.id and make every handler safe to run twice. Persist the event ID inside the same transaction as the side effect — that closes the gap where a crash between "did the work" and "marked it seen" would otherwise double-apply.

async function handleEvent(event) {
  // INSERT ... ON CONFLICT DO NOTHING — returns false if already processed.
  const isNew = await db.markProcessed(event.id);
  if (!isNew) return;

  switch (event.type) {
    case 'invoice.paid': {
      const invoice = event.data.object;          // inv_...
      await grantAccess(invoice.subscription, invoice.period_end);
      break;
    }
    case 'invoice.payment_failed':
      await notifyPaymentFailed(event.data.object.customer);
      break;
    case 'subscription.deleted':
      await revokeAccess(event.data.object.id);    // sub_...
      break;
    default:
      // Unhandled types are fine — return 200 so VINR stops retrying.
      break;
  }
}

Ordering and edge casesAskCopy

Next stepsAskCopy