Agent skill

Modem Pay Webhooks Skill

Receive and verify Modem Pay webhooks. Use when setting up Modem Pay webhook handlers, debugging x-modem-signature (HMAC-SHA512) verification, or handling charge, payment intent, customer and transfer events from the Modem Pay payment gateway.

Install this skill

npx skills add hookdeck/webhook-skills --skill modem-pay-webhooks


When to Use This Skill

  • How do I receive Modem Pay webhooks?
  • How do I verify the x-modem-signature header?
  • How do I handle charge.succeeded, payment_intent.created or transfer.failed events?
  • Why is my Modem Pay webhook signature verification failing?
  • How do I test Modem Pay webhooks locally with modempay listen?

Essential Code (USE THIS)

Modem Pay sends x-modem-signature: <hex>: the hex HMAC-SHA512 (128 characters, no sha512= prefix) of the request body, keyed with your webhook secret used as-is. There is no timestamp in the scheme.

Hash the raw body bytes. Modem Pay's own snippets hash re-serialised JSON (JSON.stringify(req.body) in Node, json.dumps(request.json) in Flask). That only works while re-serialising reproduces the exact bytes that were sent, and the Flask version uses different separators from JSON.stringify. The raw body is what was signed, and it's what Hookdeck's Modem Pay source checks.

Verification (Node.js)

const crypto = require('crypto');

// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' }), not express.json)
function verifyModemPay(rawBody, signatureHeader, secret) {
  if (!secret || typeof signatureHeader !== 'string') return false;
  const signature = signatureHeader.trim();
  if (!/^[0-9a-fA-F]{128}$/.test(signature)) return false; // validate before comparing
  const expected = Buffer.from(crypto.createHmac('sha512', secret).update(rawBody).digest('hex'));
  const received = Buffer.from(signature.toLowerCase());
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Verification (Python)

import hashlib, hmac, re

def verify_modem_pay(raw_body: bytes, header, secret: str) -> bool:
    if not secret or not header or not re.fullmatch(r"[0-9a-fA-F]{128}", header.strip()):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha512).hexdigest().encode()
    return hmac.compare_digest(header.strip().lower().encode(), expected)  # bytes, never str

Hex is compared case-insensitively. The examples answer 401 when the header is missing or empty, malformed, or doesn't match. Modem Pay's snippets answer 400; either works, because Modem Pay retries any non-2xx response.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Shape

{
  "event": "charge.succeeded",
  "payload": { "id": "23419194-…", "type": "payment", "amount": 2500, "currency": "GMD",
               "payment_method": "qmoney", "status": "completed", "test_mode": true, "…": "…" }
}

Modem Pay's docs say: "The event type is provided in the event field, while the main data is within the payload." Verify first, then check that the body is an object, event is a string and payload is an object before reading into them.

Common Event Types

EventDescription
charge.succeededA payment completed
charge.created / charge.updatedA charge was created or changed
charge.cancelled / charge.expiredA charge was cancelled or expired
payment_intent.created / payment_intent.cancelled / payment_intent.expiredPayment intent lifecycle
customer.created / customer.updated / customer.deletedCustomer lifecycle
transfer.succeeded / transfer.failed / transfer.cancelled / transfer.reversed / transfer.flaggedPayout (transfer) lifecycle

This is the list on Modem Pay's webhooks page. The CLI page's modempay trigger list also includes charge.failed. The examples handle charge.succeeded, charge.updated, payment_intent.created, customer.created, transfer.succeeded and transfer.failed, and acknowledge (200) anything else. See references/overview.md.

Important Headers

HeaderDescription
x-modem-signatureHex HMAC-SHA512 of the raw body, keyed with the webhook secret

Modem Pay's docs don't name a Content-Type or any other header, so the examples accept any content type (express.raw({ type: '*/*' }); Next.js request.arrayBuffer(); FastAPI await request.body()) and parse JSON only after verifying.

Delivery, Retries and Duplicates

Modem Pay says: "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." Timeouts, network errors and non-2xx responses count as failures. Answer 200 quickly and do slow work in a background job.

The body has no event or delivery ID, and payload.id is the charge's (or customer's, or transfer's) own ID. To make retries harmless, deduplicate on (event, payload.id). That's our suggestion, not a key Modem Pay documents. The request timeout and source IPs aren't documented either.

Environment Variables

MODEM_PAY_WEBHOOK_SECRET=your_modem_pay_webhook_secret   # Developers > Webhooks; use as-is

Modem Pay's own snippets call it MODEM_WEBHOOK_SECRET or MODEM_PAY_SECRET_HASH; it's the same value. In test mode use the secret that modempay listen prints: test and live secrets differ.

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 modem-pay --path /webhooks/modem-pay

Using Hookdeck

Hookdeck has a Modem Pay source type. Give it your webhook secret and Hookdeck's source verifies the signature on every request. Hookdeck forwards the original body and headers, so your handler can keep verifying x-modem-signature with the same secret. Hookdeck retries and replays send the same signed body, and there's no timestamp, so they verify too.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →