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-signatureheader? - How do I handle
charge.succeeded,payment_intent.createdortransfer.failedevents? - 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
| Event | Description |
|---|---|
charge.succeeded | A payment completed |
charge.created / charge.updated | A charge was created or changed |
charge.cancelled / charge.expired | A charge was cancelled or expired |
payment_intent.created / payment_intent.cancelled / payment_intent.expired | Payment intent lifecycle |
customer.created / customer.updated / customer.deleted | Customer lifecycle |
transfer.succeeded / transfer.failed / transfer.cancelled / transfer.reversed / transfer.flagged | Payout (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
| Header | Description |
|---|---|
x-modem-signature | Hex 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
- references/overview.md - Event types, payload shape, retries and what isn't documented
- references/setup.md - Getting the webhook secret, registering the endpoint, testing with the Modem Pay CLI
- references/verification.md - Signature details, common mistakes and debugging