Webhooks

OverviewAskCopy

Webhooks notify your application in real-time when events occur on your VINR account — payments completed, refunds processed, disputes opened, etc.

SetupAskCopy

1. Navigate to Dashboard → Developers → Webhooks
2. Click Add Endpoint
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to receive
5. Save — VINR will send a test event to verify connectivity

Event TypesAskCopy

Verifying SignaturesAskCopy

Always verify webhook signatures to ensure events are from VINR:

import { Vinr } from '@vinr/sdk';
import { headers } from 'next/headers';

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

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get('x-vinr-signature')!;
  const timestamp = req.headers.get('x-vinr-timestamp')!;

  try {
    const event = vinr.webhooks.constructEvent(body, signature, timestamp);
    // Process event...
    return new Response('OK');
  } catch (err) {
    return new Response('Invalid signature', { status: 401 });
  }
}

Retry PolicyAskCopy

If your endpoint returns a non-2xx status code, VINR retries with exponential backoff:

After 5 failed attempts, the webhook is marked as failed and you'll receive an email notification.

Best PracticesAskCopy

1. Return 200 quickly — Process events asynchronously
2. Handle duplicates — Use the event ID for idempotency
3. Verify signatures — Never trust unverified webhooks
4. Monitor failures — Set up alerts for webhook delivery issues