Webhooks

Receive real-time notifications when events occur in your Paygentic account

Webhooks allow your application to receive real-time notifications when events occur in your Paygentic account. When enabled, we’ll send HTTP POST requests to your configured endpoints whenever relevant events happen, such as customer creation, subscription changes, and more.

Quickstart guide

Get up and running with webhooks in just a few minutes:

1. Enable webhooks

   Navigate to the Developer > Webhooks section in your Paygentic dashboard and toggle webhooks on.

2. Configure your endpoint

   Once enabled, select “Manage Webhook Endpoints” to access the webhook management portal where you can:

   • Add your webhook endpoint URL (e.g., https://your-domain.com/webhooks/paygentic)
   • Select which event types to subscribe to
   • View your webhook signing secret
3. Test your endpoint

   Use tools like Hookdeck or ngrok to test webhooks during development without deploying to production.

4. Verify and process events

   Node.js

   import express from 'express';
   import { Webhook } from 'svix';
   
   const app = express();
   const webhookSecret = process.env.PAYGENTIC_WEBHOOK_SECRET; // Your signing secret from webhook portal
   
   app.post('/webhooks/paygentic', 
     express.raw({ type: 'application/json' }), // Important: Use raw body
     async (req, res) => {
       const headers = {
         'svix-id': req.headers['svix-id'],
         'svix-timestamp': req.headers['svix-timestamp'],
         'svix-signature': req.headers['svix-signature']
       };
   
       try {
         const wh = new Webhook(webhookSecret);
         const payload = wh.verify(req.body, headers);
         
         // Process the webhook
         console.log('Webhook verified:', payload);
         
         // Handle different event types
         switch (payload.eventType) {
           case 'customer.created.v0':
             await handleCustomerCreated(payload.data);
             break;
           case 'subscription.created.v0':
             await handleSubscriptionCreated(payload.data);
             break;
           case 'subscription.activated.v0':
             await handleSubscriptionActivated(payload.data);
             break;
           case 'payment.completed.v0':
             await handlePaymentCompleted(payload.data);
             break;
           case 'payment.failed.v0':
             await handlePaymentFailed(payload.data);
             break;
           case 'payment.expired.v0':
             await handlePaymentExpired(payload.data);
             break;
           case 'source_event.pending.v0':
             await handleSourceEventPending(payload.data);
             break;
           // Add more cases as needed
         }
         
         res.status(200).send('OK');
       } catch (err) {
         console.error('Webhook verification failed:', err);
         res.status(400).send('Webhook verification failed');
       }
     }
   );
   

   from flask import Flask, request
   from svix.webhooks import Webhook
   import os
   
   app = Flask(__name__)
   webhook_secret = os.environ.get('PAYGENTIC_WEBHOOK_SECRET')  # Your signing secret from webhook portal
   
   @app.route('/webhooks/paygentic', methods=['POST'])
   def handle_webhook():
       headers = {
           'svix-id': request.headers.get('svix-id'),
           'svix-timestamp': request.headers.get('svix-timestamp'),
           'svix-signature': request.headers.get('svix-signature')
       }
       
       try:
           wh = Webhook(webhook_secret)
           payload = wh.verify(request.data, headers)
           
           # Process the webhook
           print(f"Webhook verified: {payload}")
           
           # Handle different event types
           event_type = payload.get('eventType')
           if event_type == 'customer.created.v0':
               handle_customer_created(payload['data'])
           elif event_type == 'subscription.created.v0':
               handle_subscription_created(payload['data'])
           elif event_type == 'subscription.activated.v0':
               handle_subscription_activated(payload['data'])
           elif event_type == 'payment.completed.v0':
               handle_payment_completed(payload['data'])
           elif event_type == 'payment.failed.v0':
               handle_payment_failed(payload['data'])
           elif event_type == 'payment.expired.v0':
               handle_payment_expired(payload['data'])
           elif event_type == 'source_event.pending.v0':
               handle_source_event_pending(payload['data'])
           # Add more conditions as needed
           
           return 'OK', 200
       except Exception as e:
           print(f"Webhook verification failed: {e}")
           return 'Webhook verification failed', 400
   

Setting up webhooks

Enabling webhooks

1. Access the dashboard: Log in to your Paygentic account and navigate to Developer > Webhooks
2. Enable webhooks: Toggle the “Enable Webhooks” switch to activate webhook functionality
3. Access management portal: Select “Manage Webhook Endpoints” to open the webhook management portal

Configuring endpoints

In the webhook management portal, you can:

• Add endpoints: Specify the URL where you want to receive webhook events
• Select event types: Select which events you want to subscribe to
• Set filters: Configure advanced filtering rules if needed
• View logs: Monitor webhook deliveries and debug any issues
• Retrieve signing secret: Access your webhook signing secret for verification

Remember to keep your webhook signing secret secure and never commit it to version control. Store it in environment variables or a secure secrets management system.

Best practices

• Use HTTPS endpoints only (HTTP is not supported for security reasons)
• Implement webhook processing asynchronously to respond quickly
• Store the svix-id to handle duplicate events (idempotency)
• Disable CSRF protection for your webhook endpoint
• Respond with a 2xx status code within 15 seconds

Security and verification

Webhook security is critical to ensure that the events you receive are legitimate and have not been tampered with. Paygentic signs all webhooks with HMAC-SHA256.

Required headers

Every webhook request includes three important headers:

• svix-id: Unique identifier for the webhook message (use for idempotency)
• svix-timestamp: Unix timestamp when the webhook was sent
• svix-signature: Base64 encoded signature(s) for verification

Signature verification

Always verify webhook signatures in production. This prevents attackers from sending fake events to your endpoint.

Use Svix’s verification library for easy and secure webhook verification:

npm

npm install svix

pip install svix

go get github.com/svix/svix-webhooks/go

gem install svix

Verification examples

Node.js

import { Webhook } from 'svix';

function verifyWebhook(body, headers, secret) {
  const wh = new Webhook(secret);
  
  try {
    // Verify the webhook - throws on error
    const payload = wh.verify(body, headers);
    return { verified: true, payload };
  } catch (err) {
    return { verified: false, error: err.message };
  }
}

// Important: Use the raw request body
// Many frameworks parse JSON automatically - you need the raw string
app.use('/webhooks', express.raw({ type: 'application/json' }));

from svix.webhooks import Webhook

def verify_webhook(body, headers, secret):
    wh = Webhook(secret)
    
    try:
        # Verify the webhook - throws on error
        payload = wh.verify(body, headers)
        return {"verified": True, "payload": payload}
    except Exception as e:
        return {"verified": False, "error": str(e)}

# Important: Use the raw request body
# In Flask: request.data
# In Django: request.body
# In FastAPI: await request.body()

Replay attack protection

The timestamp in the svix-timestamp header protects against replay attacks. The Svix library automatically rejects webhooks with timestamps more than 5 minutes old (past or future). Ensure your server’s clock is synchronized using NTP.

Handling webhooks

Response requirements

• Status code: Return a 2xx status code (200-299) to indicate successful receipt
• Timeout: Respond within 15 seconds or the delivery will be considered failed
• Body: The response body is ignored - a simple “OK” or empty response is fine

Processing best practices

app.post('/webhooks/paygentic', async (req, res) => {
  // 1. Verify the webhook (as shown above)
  const payload = verifyWebhook(req.body, headers, secret);
  
  // 2. Respond immediately
  res.status(200).send('OK');
  
  // 3. Process asynchronously (do not block the response)
  setImmediate(async () => {
    try {
      await processWebhookAsync(payload);
    } catch (error) {
      console.error('Error processing webhook:', error);
      // Log to your error tracking service
    }
  });
});

Idempotency

Use the svix-id header to ensure you only process each event once:

const processedEvents = new Set(); // In production, use Redis or a database

async function processWebhook(payload, svixId) {
  if (processedEvents.has(svixId)) {
    console.log(`Event ${svixId} already processed, skipping`);
    return;
  }
  
  // Process the event
  await handleEvent(payload);
  
  // Mark as processed
  processedEvents.add(svixId);
}

CSRF protection

Disable CSRF protection for webhook endpoints. Webhooks are verified using signatures, not CSRF tokens.

Express.js

// Disable CSRF for webhook route
app.use('/webhooks', (req, res, next) => {
  req.csrfToken = () => ''; // Disable CSRF
  next();
});

from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def webhook_handler(request):
    # Handle webhook
    pass

Retry policy and failure handling

Automatic retry schedule

If your endpoint fails to respond successfully, we will retry with exponential backoff:

Attempt	Delay After Previous
1	Immediately
2	5 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	5 hours
7	10 hours
8	10 hours

Failure scenarios

A webhook delivery is considered failed if:

• Your endpoint returns a non-2xx status code
• Your endpoint does not respond within 15 seconds
• The endpoint is unreachable (connection error)
• Your endpoint returns a 3xx redirect (not followed)

Endpoint disabling

If an endpoint fails continuously for 5 days, it will be automatically disabled. You’ll receive an operational webhook notification when this happens. You can re-enable the endpoint from the webhook management portal.

Manual recovery

You can manually retry failed webhooks through the webhook management portal:

• Individual retry: Retry a specific failed message
• Bulk recovery: Replay all failed messages from a specific date
• View logs: Inspect delivery attempts and error messages

Event types reference

Paygentic currently supports the following webhook event types:

Customer Events

customer.created.v0

Triggered when a new customer is successfully created.

{
  "eventType": "customer.created.v0",
  "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "customerId": "cust_123abc",
    "merchantId": "org_456def",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

customer.creation_failed.v0

Triggered when customer creation fails.

{
  "eventType": "customer.creation_failed.v0",
  "eventId": "evt_Xrc2l84sYqstUn8Reis49H",
  "timestamp": "2024-01-15T10:31:00.000Z",
  "data": {
    "merchantId": "org_456def",
    "error": {
      "code": "validation_failed",
      "message": "Required field 'email' is missing"
    },
    "attemptedAt": "2024-01-15T10:31:00.000Z"
  }
}

Subscription Events

subscription.created.v0

Triggered when a new subscription is created.

{
  "eventType": "subscription.created.v0",
  "eventId": "evt_Zsd3m95tZrtuVo9Sfjt51I",
  "timestamp": "2024-01-15T11:00:00.000Z",
  "data": {
    "subscriptionId": "sub_789ghi",
    "customerId": "cust_123abc",
    "planId": "plan_456def",
    "planName": "Professional Plan",
    "merchantId": "org_456def",
    "status": "active",
    "startedAt": "2024-01-15T11:00:00.000Z"
  }
}

subscription.activated.v0

Triggered when a subscription becomes active and ready for use.

This event fires when a subscription transitions to the active state, which happens either:

• Immediately upon creation for subscriptions without upfront costs
• After successful payment of upfront costs for subscriptions requiring wallet prefunding

Key distinction: While subscription.created.v0 fires when a subscription is first created (which may be in pending_payment state), subscription.activated.v0 fires when the subscription is ready for use. Use this event to provision access or activate features for customers.

{
  "eventType": "subscription.activated.v0",
  "eventId": "evt_Act1v8d9Bvz0bu5Ylq17O",
  "timestamp": "2024-01-15T11:00:00.000Z",
  "data": {
    "subscriptionId": "sub_789ghi",
    "customerId": "cust_123abc",
    "merchantId": "org_456def",
    "planId": "plan_456def",
    "planName": "Professional Plan",
    "activatedAt": "2024-01-15T11:00:00.000Z",
    "paymentMethod": "wallet_prefund"
  }
}

Best practice: Listen to subscription.activated.v0 for production-readiness signals and service provisioning, rather than subscription.created.v0, to ensure the subscription has been fully funded and is ready for use.

subscription.cancelled.v0

Triggered when a subscription is cancelled.

{
  "eventType": "subscription.cancelled.v0",
  "eventId": "evt_Ate4n06uAsuVwp0Tgku62J",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "data": {
    "subscriptionId": "sub_789ghi",
    "customerId": "cust_123abc",
    "merchantId": "org_456def",
    "cancelledAt": "2024-01-15T12:00:00.000Z",
    "reason": "customer_request"
  }
}

subscription.updated.v0

Triggered when a subscription is updated (e.g., plan change, quantity adjustment).

{
  "eventType": "subscription.updated.v0",
  "eventId": "evt_Buf5o17vBtvWxq1Uhlv73K",
  "timestamp": "2024-01-15T13:00:00.000Z",
  "data": {
    "subscriptionId": "sub_789ghi",
    "customerId": "cust_123abc",
    "merchantId": "org_456def",
    "updates": {
      "status": "paused",
      "planId": "plan_789ghi"
    },
    "updatedAt": "2024-01-15T13:00:00.000Z"
  }
}

Payment Events

payment.completed.v0

Triggered when a payment is successfully completed.

{
  "eventType": "payment.completed.v0",
  "eventId": "evt_Xrb2l84sYqsuUn8Rem5s49H",
  "timestamp": "2026-03-03T12:00:00.000Z",
  "data": {
    "paymentId": "pay_a1b2c3d4e5f6g7h8i9j0",
    "merchantId": "org_f7g8h9i0j1k2l3m4",
    "customerId": "cus_p1q2r3s4t5u6v7w8",
    "amount": "49.99",
    "currency": "USD",
    "reference": "ORD-12345",
    "completedAt": "2026-03-03T12:00:00.000Z"
  }
}

payment.failed.v0

Triggered when a payment attempt fails. Includes error details from the payment processor.

{
  "eventType": "payment.failed.v0",
  "eventId": "evt_Abc2k93rXprtTm8Qdlr49H",
  "timestamp": "2026-03-03T12:00:00.000Z",
  "data": {
    "paymentId": "pay_a1b2c3d4e5f6g7h8i9j0",
    "merchantId": "org_f7g8h9i0j1k2l3m4",
    "customerId": "cus_p1q2r3s4t5u6v7w8",
    "amount": "49.99",
    "currency": "USD",
    "reference": "ORD-12345",
    "error": {
      "code": "card_declined",
      "message": "Your card was declined"
    },
    "failedAt": "2026-03-03T12:00:00.000Z"
  }
}

payment.expired.v0

Triggered when a payment session expires before the customer completes it.

{
  "eventType": "payment.expired.v0",
  "eventId": "evt_Def3m84tZrstVn9Sem6t50I",
  "timestamp": "2026-03-03T12:00:00.000Z",
  "data": {
    "paymentId": "pay_a1b2c3d4e5f6g7h8i9j0",
    "merchantId": "org_f7g8h9i0j1k2l3m4",
    "amount": "49.99",
    "currency": "USD",
    "reference": "ORD-12345",
    "expiredAt": "2026-03-03T12:00:00.000Z"
  }
}

Invoice Events

invoice.issued.v0

Triggered when an invoice is issued and a payment session is opened.

{
  "eventType": "invoice.issued.v0",
  "eventId": "evt_Zrf5n95uYqstWp9Sgn7v60J",
  "timestamp": "2026-03-03T12:00:00.000Z",
  "data": {
    "invoiceId": "inv_a1b2c3d4e5f6g7h8",
    "subscriptionId": "sub_z9a0b1c2d3e4f5g6",
    "customerId": "cus_p1q2r3s4t5u6v7w8",
    "merchantId": "org_f7g8h9i0j1k2l3m4",
    "status": "ISSUED",
    "invoiceNumber": "INV-2026-000001",
    "periodStart": "2026-03-01T00:00:00.000Z",
    "periodEnd": "2026-04-01T00:00:00.000Z",
    "subtotal": "49.99",
    "totalTax": "0.00",
    "grandTotal": "49.99",
    "issuedAt": "2026-03-03T12:00:00.000Z"
  }
}

invoice.paid.v0

Triggered when an invoice transitions to PAID — covers subscription renewals, grant purchases (the grantId is included in the payload), out-of-band payments, and zero-amount invoices.

{
  "eventType": "invoice.paid.v0",
  "eventId": "evt_Vsk6q06vZrtsXq0Tho8w71K",
  "timestamp": "2026-03-03T12:05:00.000Z",
  "data": {
    "invoiceId": "inv_a1b2c3d4e5f6g7h8",
    "subscriptionId": "sub_z9a0b1c2d3e4f5g6",
    "customerId": "cus_p1q2r3s4t5u6v7w8",
    "merchantId": "org_f7g8h9i0j1k2l3m4",
    "status": "PAID",
    "invoiceNumber": "INV-2026-000001",
    "periodStart": "2026-03-01T00:00:00.000Z",
    "periodEnd": "2026-04-01T00:00:00.000Z",
    "subtotal": "49.99",
    "totalTax": "0.00",
    "grandTotal": "49.99",
    "paidAt": "2026-03-03T12:05:00.000Z",
    "currency": "USD",
    "paymentIntentId": "pi_3OabcDEF456ghi",
    "grantId": "grt_v1w2x3y4z5"
  }
}

grantId is populated only when the invoice was created via POST /v1/entitlements/{id}/grants/purchase; otherwise it is omitted. paymentIntentId is present for Stripe-routed payments and omitted for out-of-band and zero-amount invoices.

grandTotal is the authoritative amount paid. subtotal and totalTax are each rounded to 2 decimal places independently, so re-adding them can land a cent off grandTotal — use grandTotal directly rather than re-summing the parts.

This event is delivered at least once. On rare retries you may receive the same invoice.paid.v0 more than once for a given invoice — dedupe on invoiceId (or the Svix message idempotency key) before acting on it.

Source Events

source.activated.v0

Triggered when a usage source is successfully activated and connected.

{
  "eventType": "source.activated.v0",
  "eventId": "evt_Cuf6p28wCuwXyr2Vim84L",
  "timestamp": "2024-01-15T14:00:00.000Z",
  "data": {
    "sourceId": "src_abc123",
    "sourceType": "stripe_revenue",
    "subscriptionId": "sub_789ghi",
    "customerId": "cust_123abc",
    "merchantId": "org_456def",
    "provider": "stripe",
    "activatedAt": "2024-01-15T14:00:00.000Z"
  }
}

source.activation_failed.v0

Triggered when a usage source fails to activate due to configuration or authentication issues.

{
  "eventType": "source.activation_failed.v0",
  "eventId": "evt_Dvg7q39xDvxYzs3Wjo95M",
  "timestamp": "2024-01-15T14:05:00.000Z",
  "data": {
    "sourceId": "src_abc123",
    "sourceType": "stripe_revenue",
    "subscriptionId": "sub_789ghi",
    "customerId": "cust_123abc",
    "merchantId": "org_456def",
    "error": {
      "code": "authentication_failed",
      "message": "Invalid API key provided"
    },
    "attemptedAt": "2024-01-15T14:05:00.000Z"
  }
}

source.disconnected.v0

Triggered when a usage source is disconnected or deactivated.

{
  "eventType": "source.disconnected.v0",
  "eventId": "evt_Ewh8r40yEwyZat4Xkp06N",
  "timestamp": "2024-01-15T15:00:00.000Z",
  "data": {
    "sourceId": "src_abc123",
    "sourceType": "stripe_revenue",
    "subscriptionId": "sub_789ghi",
    "customerId": "cust_123abc",
    "merchantId": "org_456def",
    "reason": "user_initiated",
    "disconnectedAt": "2024-01-15T15:00:00.000Z"
  }
}

Source Event Processing

source_event.pending.v0

Triggered when a source event enters pending state and requires manual processing.

{
  "eventType": "source_event.pending.v0",
  "eventId": "evt_SrcEvt1k73rXprtTm7Qdlr38G",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "sourceEventId": "sev_123abc",
    "sourceId": "src_456def",
    "sourceType": "stripe_revenue",
    "planId": "plan_789ghi",
    "subscriptionId": "sub_abc123",
    "merchantId": "org_def456",
    "externalEventId": "inv_stripe_xyz789",
    "status": "pending",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

source_event.processed.v0

Triggered when a source event is successfully processed into usage events.

{
  "eventType": "source_event.processed.v0",
  "eventId": "evt_SrcEvt2k73rXprtTm7Qdlr38G",
  "timestamp": "2024-01-15T10:35:00.000Z",
  "data": {
    "sourceEventId": "sev_123abc",
    "sourceId": "src_456def",
    "sourceType": "stripe_revenue",
    "planId": "plan_789ghi",
    "subscriptionId": "sub_abc123",
    "merchantId": "org_def456",
    "externalEventId": "inv_stripe_xyz789",
    "status": "processed",
    "previousStatus": "pending",
    "usageEventIds": ["ue_111aaa", "ue_222bbb"],
    "processedBy": "user_xyz123",
    "processedAt": "2024-01-15T10:35:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z"
  }
}

source_event.failed.v0

Triggered when a source event fails to process due to errors.

{
  "eventType": "source_event.failed.v0",
  "eventId": "evt_SrcEvt3k73rXprtTm7Qdlr38G",
  "timestamp": "2024-01-15T10:32:00.000Z",
  "data": {
    "sourceEventId": "sev_456def",
    "sourceId": "src_789ghi",
    "sourceType": "stripe_revenue",
    "planId": "plan_abc123",
    "subscriptionId": "sub_def456",
    "merchantId": "org_ghi789",
    "externalEventId": "inv_stripe_abc456",
    "status": "failed",
    "previousStatus": "pending",
    "errorMessage": "Unable to transform event data: missing required field 'amount'",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:32:00.000Z"
  }
}

source_event.rejected.v0

Triggered when a source event is manually rejected by a user.

{
  "eventType": "source_event.rejected.v0",
  "eventId": "evt_SrcEvt4k73rXprtTm7Qdlr38G",
  "timestamp": "2024-01-15T10:40:00.000Z",
  "data": {
    "sourceEventId": "sev_789ghi",
    "sourceId": "src_abc123",
    "sourceType": "stripe_revenue",
    "planId": "plan_def456",
    "subscriptionId": "sub_ghi789",
    "merchantId": "org_jkl012",
    "externalEventId": "inv_stripe_def789",
    "status": "rejected",
    "previousStatus": "pending",
    "rejectionReason": "Duplicate invoice detected",
    "processedBy": "user_abc456",
    "processedAt": "2024-01-15T10:40:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:40:00.000Z"
  }
}

Common event fields

All webhook events include these standard fields:

Field	Type	Description
eventType	string	The type of event (e.g., customer.created.v0)
eventId	string	Unique identifier for this specific event
timestamp	string	ISO 8601 timestamp when the event occurred
data	object	Event-specific data payload

Code examples

Complete webhook handler

Here’s a production-ready webhook handler example:

Node.js

import express from 'express';
import { Webhook } from 'svix';
import Redis from 'ioredis';

const app = express();
const redis = new Redis(process.env.REDIS_URL);
const webhookSecret = process.env.PAYGENTIC_WEBHOOK_SECRET;

// Webhook handler with all best practices
app.post('/webhooks/paygentic',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const svixId = req.headers['svix-id'];
    const svixTimestamp = req.headers['svix-timestamp'];
    const svixSignature = req.headers['svix-signature'];

    // Check required headers
    if (!svixId || !svixTimestamp || !svixSignature) {
      return res.status(400).send('Missing required headers');
    }

    try {
      // Verify webhook signature
      const wh = new Webhook(webhookSecret);
      const payload = wh.verify(req.body, {
        'svix-id': svixId,
        'svix-timestamp': svixTimestamp,
        'svix-signature': svixSignature
      });

      // Check for duplicate processing (idempotency)
      const processed = await redis.get(`webhook:${svixId}`);
      if (processed) {
        console.log(`Webhook ${svixId} already processed`);
        return res.status(200).send('Already processed');
      }

      // Mark as processed (with 24 hour expiry)
      await redis.setex(`webhook:${svixId}`, 86400, 'processed');

      // Respond immediately
      res.status(200).send('OK');

      // Process asynchronously
      setImmediate(async () => {
        try {
          await processWebhookEvent(payload);
        } catch (error) {
          console.error('Error processing webhook:', error);
          // Send to error tracking service
          // Consider implementing a retry queue
        }
      });

    } catch (err) {
      console.error('Webhook verification failed:', err);
      return res.status(400).send('Invalid webhook');
    }
  }
);

async function processWebhookEvent(payload) {
  const { eventType, data } = payload;
  
  console.log(`Processing event: ${eventType}`);
  
  switch (eventType) {
    case 'customer.created.v0':
      await handleCustomerCreated(data);
      break;

    case 'customer.creation_failed.v0':
      await handleCustomerCreationFailed(data);
      break;

    case 'subscription.created.v0':
      await handleSubscriptionCreated(data);
      break;

    case 'subscription.activated.v0':
      await handleSubscriptionActivated(data);
      break;

    case 'subscription.cancelled.v0':
      await handleSubscriptionCancelled(data);
      break;

    case 'subscription.updated.v0':
      await handleSubscriptionUpdated(data);
      break;

    case 'payment.completed.v0':
      await handlePaymentCompleted(data);
      break;

    case 'payment.failed.v0':
      await handlePaymentFailed(data);
      break;

    case 'payment.expired.v0':
      await handlePaymentExpired(data);
      break;

    case 'source_event.pending.v0':
      await handleSourceEventPending(data);
      break;

    default:
      console.log(`Unhandled event type: ${eventType}`);
  }
}

// Event handlers
async function handleCustomerCreated(data) {
  console.log('New customer created:', data.customerId);
  // Your business logic here
}

async function handleSubscriptionCreated(data) {
  console.log('New subscription created:', data.subscriptionId);
  // Your business logic here
}

async function handleSubscriptionActivated(data) {
  console.log('Subscription activated:', data.subscriptionId);
  // Provision access, activate features, etc.
  // Your business logic here
}

async function handleSourceEventPending(data) {
  console.log('Source event requires manual processing:', data.sourceEventId);
  // Your business logic here
}

// ... implement other handlers

from flask import Flask, request, jsonify
import os
import json
import redis
from svix.webhooks import Webhook
from threading import Thread

app = Flask(__name__)
redis_client = redis.from_url(os.environ.get('REDIS_URL'))
webhook_secret = os.environ.get('PAYGENTIC_WEBHOOK_SECRET')

@app.route('/webhooks/paygentic', methods=['POST'])
def handle_webhook():
    svix_id = request.headers.get('svix-id')
    svix_timestamp = request.headers.get('svix-timestamp')
    svix_signature = request.headers.get('svix-signature')
    
    # Check required headers
    if not all([svix_id, svix_timestamp, svix_signature]):
        return 'Missing required headers', 400
    
    try:
        # Verify webhook signature
        wh = Webhook(webhook_secret)
        payload = wh.verify(request.data, {
            'svix-id': svix_id,
            'svix-timestamp': svix_timestamp,
            'svix-signature': svix_signature
        })
        
        # Check for duplicate processing (idempotency)
        if redis_client.get(f"webhook:{svix_id}"):
            print(f"Webhook {svix_id} already processed")
            return 'Already processed', 200
        
        # Mark as processed (with 24 hour expiry)
        redis_client.setex(f"webhook:{svix_id}", 86400, 'processed')
        
        # Process asynchronously
        thread = Thread(target=process_webhook_event, args=(payload,))
        thread.daemon = True
        thread.start()
        
        # Respond immediately
        return 'OK', 200
        
    except Exception as e:
        print(f"Webhook verification failed: {e}")
        return 'Invalid webhook', 400

def process_webhook_event(payload):
    event_type = payload.get('eventType')
    data = payload.get('data')
    
    print(f"Processing event: {event_type}")
    
    try:
        if event_type == 'customer.created.v0':
            handle_customer_created(data)
        elif event_type == 'customer.creation_failed.v0':
            handle_customer_creation_failed(data)
        elif event_type == 'subscription.created.v0':
            handle_subscription_created(data)
        elif event_type == 'subscription.activated.v0':
            handle_subscription_activated(data)
        elif event_type == 'subscription.cancelled.v0':
            handle_subscription_cancelled(data)
        elif event_type == 'payment.completed.v0':
            handle_payment_completed(data)
        elif event_type == 'payment.failed.v0':
            handle_payment_failed(data)
        elif event_type == 'payment.expired.v0':
            handle_payment_expired(data)
        elif event_type == 'source_event.pending.v0':
            handle_source_event_pending(data)
        else:
            print(f"Unhandled event type: {event_type}")
    except Exception as e:
        print(f"Error processing webhook: {e}")
        # Send to error tracking service
        # Consider implementing a retry queue

# Event handlers
def handle_customer_created(data):
    print(f"New customer created: {data.get('customerId')}")
    # Your business logic here

def handle_subscription_created(data):
    print(f"New subscription created: {data.get('subscriptionId')}")
    # Your business logic here

def handle_subscription_activated(data):
    print(f"Subscription activated: {data.get('subscriptionId')}")
    # Provision access, activate features, etc.
    # Your business logic here

def handle_source_event_pending(data):
    print(f"Source event requires manual processing: {data.get('sourceEventId')}")
    # Your business logic here

# ... implement other handlers

if __name__ == '__main__':
    app.run(debug=False)

Testing webhooks locally

For local development, use a tunneling service to expose your local server:

# Using ngrok
ngrok http 3000

# Using Hookdeck CLI
hookdeck listen 3000

# Your webhook URL will be something like:
# https://abc123.ngrok.io/webhooks/paygentic

Then add this URL as your webhook endpoint in the webhook management portal for testing.

Additional resources

• Webhook Management Portal - Manage your webhook endpoints and view logs
• Paygentic API Documentation - Complete API reference

Need help?

If you encounter any issues with webhooks:

1. Check the delivery logs in the webhook management portal for error messages
2. Verify your endpoint is returning a 2xx status code
3. Ensure you’re using the correct signing secret
4. Confirm your server’s clock is synchronized (for timestamp validation)
5. Contact support if you need additional assistance