Webhooks API

Webhooks allow you to receive real-time notifications about events in your Notch Pay account. Instead of polling the API for updates, webhooks push data to your server when events occur.

How Webhooks Work

Create a Webhook Endpoint

First, create an endpoint on your server that can receive HTTP POST requests. This endpoint will process webhook events from Notch Pay.

Register your endpoint URL with Notch Pay through the API or dashboard. You can specify which events you want to receive.

Receive Events

When an event occurs (like a payment with status “complete”), Notch Pay sends a POST request to your endpoint with event data.

Process the Event

Your endpoint processes the event data and takes appropriate action (e.g., fulfilling an order after a payment).

Respond with 200 OK

Your endpoint should respond with a 200 OK status code to acknowledge receipt of the webhook.

Webhook Event Object

{
  "id": "evt_123456789",
  "type": "payment.complete",
  "created_at": "2023-01-01T12:00:00Z",
  "data": {
    "id": "pay_123456789",
    "reference": "order_123",
    "amount": 5000,
    "currency": "XAF",
    "status": "complete",
    "customer": "cus_123456789",
    "created_at": "2023-01-01T12:00:00Z",
    "completed_at": "2023-01-01T12:05:00Z"
  }
}

Webhook Event Properties

string

Unique identifier for the event

type

string

Type of event (e.g., payment.complete, transfer.failed)

created_at

string

Timestamp when the event was created

data

object

The resource that triggered the event (e.g., a payment or transfer object)

API Endpoints

List Webhooks

GET /webhooks

Retrieve a list of all webhook endpoints for your account.

Query Parameters

limit

integer

Number of items per page (default: 30, max: 100)

page

integer

Page number (default: 1)

GET /webhooks

Retrieve a list of all webhook endpoints for your account.

Query Parameters

limit

integer

Number of items per page (default: 30, max: 100)

page

integer

Page number (default: 1)

{
  "code": 200,
  "status": "OK",
  "message": "Webhooks retrieved",
  "data": [
    {
      "id": "wh_123456789",
      "url": "https://example.com/webhooks",
      "events": ["payment.complete", "payment.failed"],
      "active": true,
      "created_at": "2023-01-01T12:00:00Z"
    },
    // More webhooks...
  ]
}

Create a Webhook

POST /webhooks

Create a new webhook endpoint.

Request Parameters

url

string

required

The URL where webhook events will be sent

events

array

required

Array of event types to subscribe to

description

string

Description of the webhook

active

boolean

Whether the webhook is active (default: true)

Example Request

{
  "url": "https://example.com/webhooks",
  "events": ["payment.complete", "payment.failed"],
  "description": "Payment notifications for my e-commerce site"
}

POST /webhooks

Create a new webhook endpoint.

Request Parameters

url

string

required

The URL where webhook events will be sent

events

array

required

Array of event types to subscribe to

description

string

Description of the webhook

active

boolean

Whether the webhook is active (default: true)

Example Request

{
  "url": "https://example.com/webhooks",
  "events": ["payment.complete", "payment.failed"],
  "description": "Payment notifications for my e-commerce site"
}

{
  "code": 201,
  "status": "Created",
  "message": "Webhook created",
  "data": {
    "id": "wh_123456789",
    "url": "https://example.com/webhooks",
    "events": ["payment.complete", "payment.failed"],
    "description": "Payment notifications for my e-commerce site",
    "active": true,
    "created_at": "2023-01-01T12:00:00Z"
  }
}

Retrieve a Webhook

GET /webhooks/{id}

Retrieve details of a specific webhook.

Path Parameters

string

required

ID of the webhook to retrieve

GET /webhooks/{id}

Retrieve details of a specific webhook.

Path Parameters

string

required

ID of the webhook to retrieve

{
  "code": 200,
  "status": "OK",
  "message": "Webhook retrieved",
  "data": {
    "id": "wh_123456789",
    "url": "https://example.com/webhooks",
    "events": ["payment.complete", "payment.failed"],
    "description": "Payment notifications for my e-commerce site",
    "active": true,
    "created_at": "2023-01-01T12:00:00Z"
  }
}

Update a Webhook

PUT /webhooks/{id}

Update an existing webhook.

Path Parameters

string

required

ID of the webhook to update

Request Parameters

url

string

The URL where webhook events will be sent

events

array

Array of event types to subscribe to

description

string

Description of the webhook

active

boolean

Whether the webhook is active

Example Request

{
  "events": ["payment.complete", "payment.failed", "transfer.complete"],
  "active": true
}

PUT /webhooks/{id}

Update an existing webhook.

Path Parameters

string

required

ID of the webhook to update

Request Parameters

url

string

The URL where webhook events will be sent

events

array

Array of event types to subscribe to

description

string

Description of the webhook

active

boolean

Whether the webhook is active

Example Request

{
  "events": ["payment.complete", "payment.failed", "transfer.complete"],
  "active": true
}

{
  "code": 200,
  "status": "OK",
  "message": "Webhook updated",
  "data": {
    "id": "wh_123456789",
    "url": "https://example.com/webhooks",
    "events": ["payment.complete", "payment.failed", "transfer.complete"],
    "description": "Payment notifications for my e-commerce site",
    "active": true,
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-02T12:00:00Z"
  }
}

Delete a Webhook

DELETE /webhooks/{id}

Delete a webhook endpoint.

Path Parameters

string

required

ID of the webhook to delete

Event Types

Available Event Types

Webhook Security

Retrieve Your Webhook Secret

Each webhook has a secret that you can find in your dashboard or when creating a webhook via the API.

Extract the Signature

When Notch Pay sends a webhook, it includes a X-Notch-Signature header with a signature.

Verify the Signature

const crypto = require('crypto');

function verifyWebhookSignature(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')
  );
}

// In your webhook handler
app.post('/webhooks', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-notch-signature'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(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');
});

Best Practices

Respond Quickly

Respond to webhooks with a 200 status code as quickly as possible, even before processing the event. This prevents Notch Pay from retrying the webhook.

Process the event asynchronously if it requires time-consuming operations.

Handle Retries

Notch Pay will retry failed webhook deliveries several times with increasing delays. Make your webhook handler idempotent to avoid processing the same event multiple times.

Store the event ID and check if you’ve already processed it before taking action.

Monitor Webhook Health

Regularly check your webhook logs in the Notch Pay dashboard to ensure they’re being delivered correctly.

Set up monitoring for your webhook endpoint to detect and alert on failures.

Use HTTPS

Always use HTTPS for your webhook endpoints to ensure the data is encrypted in transit.

Use a valid SSL certificate from a trusted certificate authority.

Testing Webhooks

Go to Webhooks Section

Navigate to the Webhooks section in your Notch Pay dashboard.

Select a Webhook

Select the webhook you want to test.

Click 'Send Test Event'

Click the “Send Test Event” button and select the event type you want to test.

Check Your Logs

Check your server logs to confirm that the test event was received and processed correctly.

Go to Webhooks Section

Navigate to the Webhooks section in your Notch Pay dashboard.

Select a Webhook

Select the webhook you want to test.

Click 'Send Test Event'

Click the “Send Test Event” button and select the event type you want to test.

Check Your Logs

Check your server logs to confirm that the test event was received and processed correctly.

Set Up a Webhook Debugger

Use a service like webhook.site or Beeceptor to get a temporary URL for testing.

Create a Test Webhook

Create a new webhook in your Notch Pay account using the temporary URL.

Trigger Events

Trigger events (like creating a test payment) to see the webhook payloads in real-time.

Analyze the Payload

Analyze the webhook payload to understand the data structure and implement your handler accordingly.

Use a Tunnel Service

Use a service like ngrok or Localtunnel to expose your local server to the internet.

# Example with ngrok
ngrok http 3000

Create a Webhook

Create a webhook in your Notch Pay account using the tunnel URL.

https://abc123.ngrok.io/webhooks

Implement Your Handler

Implement your webhook handler in your local development environment.

Trigger Events

Trigger events in your Notch Pay test account to test your handler.

Troubleshooting

Webhook Not Receiving Events

Invalid Signature Errors

Duplicate Events

Implement Idempotency

Store processed event IDs and check for duplicates before processing.

// Example with a database
async function handleWebhook(event) {
  // Check if we've already processed this event
  const existingEvent = await db.events.findOne({ id: event.id });
  if (existingEvent) {
    console.log(`Event ${event.id} already processed, skipping`);
    return;
  }

  // Process the event
  await processEvent(event);

  // Store the event ID to prevent duplicate processing
  await db.events.insertOne({ id: event.id, processed_at: new Date() });
}

Use Database Constraints

Use unique constraints in your database to prevent duplicate event processing.

Introduction

Core Resources

Additional Resources

API Specification

​Webhooks API

​How Webhooks Work

​Webhook Event Object

​Webhook Event Properties

​API Endpoints

List Webhooks

​Query Parameters

​Query Parameters

Create a Webhook

​Request Parameters

​Example Request

​Request Parameters

​Example Request

Retrieve a Webhook

​Path Parameters

​Path Parameters

Update a Webhook

​Path Parameters

​Request Parameters

​Example Request

​Path Parameters

​Request Parameters

​Example Request

Delete a Webhook

​Path Parameters

​Path Parameters

​Event Types

​Webhook Security

​Best Practices

Respond Quickly

Handle Retries

Monitor Webhook Health

Use HTTPS

​Testing Webhooks

​Troubleshooting

Webhooks API

How Webhooks Work

Webhook Event Object

Webhook Event Properties

API Endpoints

Query Parameters

Query Parameters

Request Parameters

Example Request

Request Parameters

Example Request

Path Parameters

Path Parameters

Path Parameters

Request Parameters

Example Request

Path Parameters

Request Parameters

Example Request

Path Parameters

Path Parameters

Event Types

Webhook Security

Best Practices

Testing Webhooks

Troubleshooting