Webhooks

Webhooks

Real-time event notifications for your application.

Overview

Webhooks deliver events to your application as they happen:

sequenceDiagram
    autonumber
    participant IOF as 🏛️ Islamic Open Finance™
    participant Server as 🖥️ Your Server

    Note over IOF,Server: Webhook Delivery Flow

    IOF->>+Server: 📤 POST /webhooks
    Note right of Server: 🔐 Verify HMAC signature
    Note right of Server: ✅ Process event data
    Server-->>-IOF: 📨 200 OK

    Note over IOF: ✅ Delivery confirmed

Event Types

Contract Events

Event	Description
contract.created	New contract created
contract.activated	Contract activated
contract.payment.received	Payment received
contract.matured	Contract reached maturity
contract.closed	Contract closed

KYC Events

Event	Description
kyc.submitted	KYC submission received
kyc.verified	KYC verified
kyc.rejected	KYC rejected
kyc.expired	KYC expired

Compliance Events

Event	Description
compliance.alert	Compliance alert triggered
compliance.review.required	Manual review needed

Webhook Payload

{
  "id": "evt_abc123",
  "type": "contract.created",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "object": {
      "id": "contract_xyz",
      "type": "MURABAHA",
      "status": "draft"
    }
  },
  "metadata": {
    "workspaceId": "ws_123",
    "tenantId": "tenant_456"
  }
}

Creating Endpoints

const endpoint = await iof.webhooks.createEndpoint({
  url: "https://yourapp.com/webhooks",
  events: ["contract.*", "kyc.verified"],
  secret: process.env.WEBHOOK_SECRET,
});

Handling Webhooks

app.post("/webhooks", async (req, res) => {
  // Verify signature
  const isValid = iof.webhooks.verify(
    req.rawBody,
    req.headers["x-iof-signature"],
    process.env.WEBHOOK_SECRET,
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;

  switch (event.type) {
    case "contract.created":
      await handleContractCreated(event.data.object);
      break;
    case "kyc.verified":
      await handleKycVerified(event.data.object);
      break;
  }

  res.status(200).send("OK");
});

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

Next Steps

• Webhooks API - Full API reference
• Security - Signature verification