Webhooks

Webhooks notify your systems in real time when events happen — a payment succeeds, a merchant is activated, a settlement completes. Register an endpoint and react to events as they arrive.

Event structure

Each event has an id, a type and a dataobject describing the resource that changed.

POST https://your-app.com/webhooks/madfoa

{
  "id": "evt_9f2b7c",
  "type": "payment.succeeded",
  "created_at": "2026-08-06T10:24:03Z",
  "data": {
    "id": "pay_3ab19f",
    "status": "succeeded",
    "amount": 4500,
    "currency": "SAR",
    "merchant_id": "mch_08c1a2"
  }
}

Common event types

• payment.succeeded / payment.failed
• merchant.activated
• settlement.completed
• refund.succeeded

Verifying signatures

Every delivery includes a Madfoa-Signature header. Verify it against your webhook secret before trusting the payload.

import { verifyWebhook } from "@madfoa/node";

const event = verifyWebhook(
  request.rawBody,
  request.headers["madfoa-signature"],
  process.env.MADFOA_WEBHOOK_SECRET
);

if (event.type === "payment.succeeded") {
  // fulfil the order
}

Next: SDKs →