# 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)

```javascript
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)

```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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/modem-pay-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/modem-pay-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/modem-pay-webhooks/examples/fastapi/).

## Event Shape

```json
{
  "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](https://github.com/hookdeck/webhook-skills/blob/main/skills/modem-pay-webhooks/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

```bash
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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/modem-pay-webhooks/references/overview.md) - Event types, payload shape, retries and what isn't documented
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/modem-pay-webhooks/references/setup.md) - Getting the webhook secret, registering the endpoint, testing with the Modem Pay CLI
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/modem-pay-webhooks/references/verification.md) - Signature details, common mistakes and debugging