​
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

1

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.
2

Register the Endpoint

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

Receive Events

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

Process the Event

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

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

​
id
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)

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"
}

Retrieve a Webhook

GET /webhooks/{id}
Retrieve details of a specific webhook.

​
Path Parameters

​
id
string
required
ID of the webhook to retrieve

Update a Webhook

PUT /webhooks/{id}
Update an existing webhook.

​
Path Parameters

​
id
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
}

Delete a Webhook

DELETE /webhooks/{id}
Delete a webhook endpoint.

​
Path Parameters

​
id
string
required
ID of the webhook to delete

​
Event Types

Available Event Types

​
Webhook Security

1

Retrieve Your Webhook Secret

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

Extract the Signature

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

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

1

Go to Webhooks Section

Navigate to the Webhooks section in your Notch Pay dashboard.
2

Select a Webhook

Select the webhook you want to test.
3

Click 'Send Test Event'

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

Check Your Logs

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

​
Troubleshooting