Skip to main content
Modem Pay’s webhooks notify your server about key events, such as customer creation, payment intent updates, and successful charges. To receive and securely process these notifications, follow the steps outlined here for setting up, validating, and handling webhooks.
You can generate your unique Modem Pay webhook secret in the Modem Pay dashboard under Developers > Webhooks.

​
Setting Up Webhooks

  1. Define Your Webhook Endpoint:
    Create a dedicated POST endpoint on your server to receive webhook events from Modem Pay. Ensure this endpoint is accessible over HTTPS to maintain security.
  2. Listening for Events:
    Your endpoint will receive a variety of event notifications (e.g., customer.created, payment_intent.created, charge.succeeded). The event type is provided in the event field, while the main data is within the payload.

​
Sample Webhook Event

json
{
  "event": "charge.succeeded",
  "payload": {
    "id": "23419194-7324-4c2b-a74b-d8fba736e692",
    "type": "payment",
    "amount": 2500,
    "currency": "GMD",
    "payment_method": "qmoney",
    "customer": "0f6e0912-2f2f-4d8b-bd68-ac8c97c44ae6",
    "metadata": {},
    "status": "completed",
    "payment_link_id": null,
    "custom_fields_values": {},
    "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
    "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
    "test_mode": true,
    "customer_name": "Zypheron Kade",
    "customer_phone": "7024725",
    "customer_email": "calebchibuike110@gmail.com",
    "createdAt": "2024-12-15T09:34:17.036Z",
    "updatedAt": "2024-12-15T09:34:43.306Z",
    "payment_account": ".... 9944",
    "payment_metadata": {
      "os": "MacOS",
      "browser": "Firefox",
      "ipAddress": "196.223.149.183",
      "timestamp": "2024-12-15T09:34:43.266Z",
      "deviceType": "Desktop",
      "urlIPAddress": "https://db-ip.com/196.223.149.183",
      "screenResolution": "1600x900"
    },
    "payment_intent_id": "273ac751-369d-4198-8340-da480208bded",
    "transaction_reference": "VOAO1CFEN7",
    "payment_method_id": "4dbaaec5-7a16-4908-8fd9-c3d2bd24f739"
  }
}

​
Webhook Security and Signature Validation

To confirm the integrity of incoming events, Modem Pay includes a unique x-modem-signature header in each webhook request. This header allows you to verify that the event originated from Modem Pay.
  1. Retrieve the Signature:
    In your webhook endpoint, extract the x-modem-signature header from the incoming request.
  2. Use modempay.webhooks.composeEventDetails for Validation:
    Pass the payload, signature, and your unique Modem Pay secret to the modempay.webhooks.composeEventDetails function. This function performs the necessary checks, verifying the signature and parsing the payload.     
// Example usage
const event = modempay.webhooks.composeEventDetails(
    payload,
    xSignatureHeader,
    modemSecret
);

​
Modem Pay CLI

The Modem Pay CLI is a tool designed to simplify integration testing by offering features like authentication, webhook management, and event simulation only in a test environment.

​
Installation

Ensure that both Node.js and npm are installed on your machine before proceeding.
To install the Modem Pay CLI, run:
bash
npm install -g modem-pay-cli

​
Commands

​
1. Login

Authenticates a user and generates an access token, business ID, and account ID. Authentication is required to access other CLI features. Usage:
bash
$ modempay login 

✔ Please enter your Modem Pay Merchant ID (you can find this in your dashboard): › 2523017877
✔ Enter your Modem Pay email: › mercury@modempay.com
✔ Enter your password: › *******
✅ Login successful! Credentials saved.

​
2. Listen

The listen command creates a secure public tunnel using Localtunnel to forward webhooks to a local endpoint. This is particularly useful for testing webhooks during development. Disclaimer:
  • The CLI leverages Localtunnel to generate the public URL. In some cases, a public URL might not be provisioned successfully due to network issues.
  • This feature should only be used in test environments.
Usage:
bash
$ modempay listen --forward-url <local-endpoint>
Options:
  • --forward-url: Specifies your local endpoint to receive webhook events.
Example:
bash
$ modempay listen --forward-url=http://localhost:3000/webhook  

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
This will create a public tunnel pointing to http://localhost:3000/webhook.

​
3. Trigger

Simulates events for testing purposes. Usage:
bash
$ modempay trigger <event-type>
Supported Event Types:
  • Customer Events: "customer.created", "customer.updated", "customer.deleted"
  • Payment Intent Events: "payment_intent.created", "payment_intent.cancelled"
  • Charge Events: "charge.succeeded", "charge.failed", "charge.cancelled", "charge.created", "charge.updated"
The listen command captures both manually triggered events and automatically triggered events from the Modem Pay system. For testing purposes, always use the webhook secret generated by the listen command. This secret is displayed in the terminal and can also be found in the Modem Pay dashboard, but only in test mode.Important: Production secrets and endpoints remain unaffected and are not impacted by the test mode configuration.
Example:
bash
$ modempay trigger charge.succeeded 

🔧 Executing event: "charge.succeeded"
✅ Event "charge.succeeded" triggered successfully.
This sends a charge.succeeded event payload to the configured webhook endpoint for testing.
Always respond to webhook events with an HTTP 200 OK status to confirm receipt. This ensures Modem Pay doesn’t retry the webhook unnecessarily.

​
Event Structure

Upon successful validation, modempay.webhooks.composeEventDetails returns an Event object containing the event type and payload data. The event types you may receive include:
  • Customer Events: "customer.created", "customer.updated", "customer.deleted"
  • Payment Intent Events: "payment_intent.created", "payment_intent.cancelled", "payment_intent.expired"
  • Charge Events: "charge.succeeded", "charge.cancelled", "charge.created", "charge.updated", "charge.expired"
  • Payout Events: "transfer.succeeded", "transfer.cancelled", "transfer.reversed", "transfer.failed", "transfer.flagged"

​
Example Usage

Here’s an example of using modempay.webhooks.composeEventDetails to handle incoming webhooks in a Node.js application: 
const express = require("express");
const bodyParser = require("body-parser");
const ModemPay = require("modem-pay");

const modempay = new ModemPay();
const app = express();
app.use(bodyParser.json());

app.post("/webhook", (req, res) => {
  const payload = req.body;
  const signature = req.headers["x-modem-signature"];
  const secret = process.env.MODEM_WEBHOOK_SECRET;

  try {
    const event = modempay.webhooks.composeEventDetails(payload, signature, secret);
    // Process the event
    switch (event.event) {
      case "customer.created":
        // Handle new customer logic
        break;
      case "charge.succeeded":
        // Process successful payment
        break;
      // Add other cases as needed
    }

    res.status(200).send("Webhook processed!");
  } catch (error) {
    res.status(400).send("Invalid signature!");
  }
});

app.listen(3000, () => console.log("Listening for webhooks on port 3000"));
For each webhook event, respond to Modem Pay with an HTTP 200 OK status as confirmation. This ensures Modem Pay won’t re-send the event unless there’s an error response.
Ensure your webhook endpoint quickly responds with an HTTP 200 OK status before performing any tasks that might cause delays or timeouts, such as updating records or sending invoices. This prevents webhook retries and ensures smooth processing.

​
Webhook Retries

Modem Pay ensures reliable delivery of webhook events through an automatic retry mechanism. If your server fails to acknowledge a webhook event with a 200 OK HTTP response, Modem Pay will retry the delivery up to 3 times, with each retry spaced 10 minutes apart. A failure could be due to reasons such as server timeouts, network errors, or non-2xx response codes. To avoid unnecessary retries and ensure smooth webhook processing, always return a 200 OK response immediately, even if you need to carry out time-consuming tasks (like writing to a database or triggering external API calls). It’s recommended to offload such operations to a background worker or job queue. By following this best practice, you help prevent duplicate processing and reduce the risk of delays or rate-limiting due to repeated webhook attempts.

​
Summary

By following these steps, you can securely receive and process webhook events from Modem Pay, automating actions based on customer interactions and payment flows. Make sure to store and securely handle the event data, as each event may carry critical transaction or customer information relevant to your application.
⌘I