Webhooks

Overview

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

Setup

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 Types

Verifying Signatures

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 Policy

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 Practices

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