Understanding Webhooks

Learn how NextAPI webhooks provide real-time notifications for events in your account, enabling you to build responsive and automated payment systems.

What Are Webhooks?

Webhooks are automated HTTP callbacks that NextAPI sends to your server when specific events occur. Instead of continuously polling our API for status updates, you receive instant notifications as events happen.

Webhook Architecture

NextAPI → HTTP POST → Your Endpoint
    ↓           ↓
  Event    →   JSON Payload

Supported Events

Payout Events

• payout.initiated - Payout request created
• payout.pending - Payout queued for processing
• payout.processing - Payout being processed
• payout.completed - Payout successfully delivered
• payout.failed - Payout failed to process
• payout.cancelled - Payout cancelled
• payout.reversed - Completed payout reversed

Wallet Events

• wallet.credited - Funds added to wallet
• wallet.debited - Funds removed from wallet
• wallet.reserved - Funds reserved for pending operations
• wallet.low_balance - Wallet balance below threshold

Payment Link Events

• payment_link.created - New payment link generated
• payment_link.paid - Payment link successfully paid
• payment_link.expired - Payment link expired
• payment_link.cancelled - Payment link cancelled

Webhook Payload Structure

{
  "id": "evt_abc123",
  "created": 1642291200,
  "type": "payout.completed",
  "data": {
    "payout_id": "payout_456",
    "amount": 10000,
    "currency": "PHP",
    "status": "completed",
    "recipient": {
      "type": "wallet",
      "id": "wallet_789"
    },
    "processed_at": "2024-01-15T10:30:00Z"
  },
  "livemode": false
}

Setting Up Webhooks

1. Create Webhook Endpoint

// Express.js example
app.post('/webhooks/nextapi', (req, res) => {
  const signature = req.headers['nextapi-signature'];
  const payload = req.body;
  
  // Verify signature (see security section)
  if (!verifyWebhookSignature(signature, payload)) {
    return res.status(401).send('Unauthorized');
  }
  
  // Process the event
  handleWebhookEvent(payload);
  
  // Acknowledge receipt
  res.status(200).send('OK');
});

2. Configure in Dashboard

1. Go to Settings → Webhooks
2. Add your endpoint URL
3. Select events to receive
4. Set secret key for signature verification

3. Test Your Integration

Use the webhook testing tool in your dashboard to send test events.

Security

Signature Verification

NextAPI signs each webhook with a secret key:

const crypto = require('crypto');

function verifyWebhookSignature(signature, payload) {
  const secret = process.env.NEXTAPI_WEBHOOK_SECRET;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === `sha256=${expectedSignature}`;
}

Security Best Practices

1. Always verify signatures before processing events
2. Use HTTPS for your webhook endpoints
3. Implement replay protection using event IDs
4. Validate event types before processing
5. Log all webhook events for auditing

Error Handling

Retry Logic

NextAPI automatically retries failed webhook deliveries:

Attempt	Delay	Max Duration
1	Immediate	-
2	1 minute	1 minute
3	5 minutes	6 minutes
4	30 minutes	36 minutes
5	2 hours	2.5 hours

Responding Correctly

• 200-299: Success - webhook processed
• 4xx: Client error - no retry (check your implementation)
• 5xx: Server error - retry scheduled

Event Processing

Idempotency

Webhook events may be delivered multiple times. Use event IDs to prevent duplicate processing:

const processedEvents = new Set();

function handleWebhookEvent(event) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }
  
  // Process event
  processEvent(event);
  
  // Mark as processed
  processedEvents.add(event.id);
}

Async Processing

For heavy operations, acknowledge quickly and process asynchronously:

app.post('/webhooks/nextapi', (req, res) => {
  // Quick verification
  if (!verifyWebhookSignature(req.headers['nextapi-signature'], req.body)) {
    return res.status(401).send('Unauthorized');
  }
  
  // Queue for async processing
  webhookQueue.add(req.body);
  
  // Immediate acknowledgment
  res.status(200).send('OK');
});

Monitoring and Debugging

Dashboard Features

• Delivery logs: View all webhook delivery attempts
• Success rates: Monitor webhook performance
• Error details: Debug failed deliveries
• Test events: Send test webhooks on demand

Common Issues

1. SSL/TLS errors: Ensure valid SSL certificate
2. Timeout errors: Process events quickly (< 30 seconds)
3. Signature failures: Check secret key configuration
4. Duplicate events: Implement idempotency handling

Best Practices

1. Respond quickly - Acknowledge within 30 seconds
2. Implement retries - Handle temporary failures gracefully
3. Log everything - Maintain detailed webhook logs
4. Monitor health - Track webhook success rates
5. Test thoroughly - Use sandbox environment for testing

Related Concepts

• [The Lifecycle of a Payout](./the-lifecycle-of-a-payout
• [Securely Receive and Verify Webhooks](../guides/how-to/securely-receive-and-verify-webhooks
• [IDs, Reference IDs, and Idempotency](./ids-reference-ids-idempotency