Webhook Setup

Real-time Event Notifications

Learn how to set up webhooks to receive instant notifications when events occur in your Notch Pay account, enabling you to automate your business processes and provide a better customer experience.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when events happen in your Notch Pay account. Instead of your application constantly polling the Notch Pay API for updates, webhooks push events to your application as they happen.

Think of webhooks as a “phone call” from Notch Pay to your application, rather than your application repeatedly “calling” Notch Pay to check for updates.

Why Use Webhooks?

  • Real-time updates - Get notified immediately when events occur
  • Reduced API calls - No need to constantly poll for updates
  • Automation - Trigger workflows automatically
  • Better user experience - Update your UI in real-time

Implementation Overview

1

Create a Webhook Endpoint

Set up an endpoint on your server that can receive HTTP POST requests from Notch Pay.

2

Register Your Endpoint

Add your webhook URL to your Notch Pay account and select which events you want to receive.

3

Implement Signature Verification

Verify that incoming webhook requests are actually from Notch Pay by checking the signature.

4

Process Webhook Events

Handle the different types of events and update your systems accordingly.

5

Test Your Implementation

Use the Notch Pay dashboard to send test events to your webhook endpoint.

Common Use Cases

Order Management

Automatically update order status when a payment is completed, failed, or refunded. Trigger fulfillment processes and notify customers about their order status.

Customer Communications

Send confirmation emails, SMS notifications, or in-app messages to customers when their payments are processed or transfers are completed.

Inventory Management

Update your inventory systems automatically when products are purchased. Trigger reordering processes when stock levels fall below thresholds.

Analytics & Reporting

Track payment success rates, monitor failed payments, and analyze customer payment patterns. Log events for audit trails and compliance reporting.

Setting Up Your Webhook Endpoint

Your webhook endpoint should:

  1. Accept HTTP POST requests
  2. Parse JSON request bodies
  3. Respond with a 2xx status code (preferably 200 OK)
  4. Process the webhook data asynchronously if needed
const express = require('express');
const app = express();

// Parse JSON request bodies
app.use(express.json());

app.post('/webhooks/notchpay', (req, res) => {
  // Return a 200 response immediately
  res.status(200).send('Webhook received');
  
  // Process the webhook asynchronously
  const event = req.body;
  processWebhook(event);
});

function processWebhook(event) {
  const eventType = event.type;
  const eventData = event.data;
  
  switch (eventType) {
    case 'payment.complete':
      // Handle completed payment
      console.log(`Payment ${eventData.id} completed`);
      break;
    case 'payment.failed':
      // Handle failed payment
      console.log(`Payment ${eventData.id} failed`);
      break;
    // Handle other event types
  }
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Registering Your Webhook

  1. Log in to your Notch Pay Business suite
  2. Navigate to Settings > Webhooks
  3. Click “Add Endpoint”
  4. Enter your webhook URL (e.g., https://example.com/webhooks/notchpay)
  5. Select the events you want to receive
  6. Click “Save” to create the webhook

Key Webhook Events

Securing Your Webhooks

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const calculatedSignature = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(calculatedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

app.post('/webhooks/notchpay', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-notch-signature'];
  const payload = req.body.toString();
  
  if (!verifySignature(payload, signature, 'your_webhook_secret')) {
    return res.status(400).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  // Process the event
  
  res.status(200).send('Webhook received');
});

Testing Your Implementation

1

Test in the Dashboard

Use the “Test” button in your Notch Pay dashboard to send test events to your webhook endpoint.

2

Test Locally with Tunneling

For local development, use tools like ngrok to expose your local server to the internet:

# Start your local server (e.g., on port 3000)
npm start

# In another terminal, start ngrok
ngrok http 3000

Use the generated URL (e.g., https://abc123.ngrok.io/webhooks/notchpay) as your webhook endpoint.

3

Check Webhook Logs

Monitor your webhook delivery logs in the Notch Pay dashboard to ensure events are being delivered successfully.

Best Practices

Respond Quickly

Return a 200 response as soon as possible, then process the webhook asynchronously to avoid timeouts.

Verify Signatures

Always verify webhook signatures to ensure they come from Notch Pay.

Handle Duplicates

Design your webhook handler to be idempotent, as the same event might be delivered multiple times.

Implement Logging

Log all webhook events for debugging and auditing purposes.

Handle Retries

Be prepared for Notch Pay to retry failed webhook deliveries with exponential backoff.

Monitor Performance

Monitor your webhook endpoint’s performance to ensure it can handle the volume of events.

Next Steps

Secure Your Webhooks

Now that you’ve set up your webhook endpoint, it’s important to secure it by verifying webhook signatures. This ensures that webhook events are actually coming from Notch Pay and not from a malicious source.

API Reference

Explore the complete Webhooks API reference documentation for detailed information about endpoints and parameters.

View API Reference

SDK Integration

Our SDKs provide built-in support for webhook signature verification and event handling.

Explore SDKs

Troubleshooting

Having issues with your webhooks? Check our troubleshooting guide for common problems and solutions.

Troubleshooting Guide