Webhooks

Real-time event notifications for your application.

Overview

Webhooks deliver events to your application as they happen:

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: "whsec_...",
});

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