Webhooks Rail

Webhooks Rail

Event notification and webhook management endpoints.

Overview

The Webhooks rail provides:

• Webhook endpoint management
• Event delivery
• Retry handling
• Delivery logs

Endpoints

Create Endpoint

POST /v1/webhooks/endpoints

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

Response:

{
  "id": "we_abc",
  "url": "https://yourapp.com/webhooks",
  "events": ["contract.*", "kyc.verified"],
  "secret": "WEBHOOK_SECRET_SHOWN_ONCE",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Endpoint

GET /v1/webhooks/endpoints/:id

const endpoint = await iof.webhooks.getEndpoint("we_abc");

Update Endpoint

PATCH /v1/webhooks/endpoints/:id

const endpoint = await iof.webhooks.updateEndpoint("we_abc", {
  events: ["contract.*", "kyc.*", "compliance.*"],
});

Delete Endpoint

DELETE /v1/webhooks/endpoints/:id

await iof.webhooks.deleteEndpoint("we_abc");

List Events

GET /v1/webhooks/events

const events = await iof.webhooks.listEvents({
  endpointId: "we_abc",
  status: "failed",
  limit: 50,
});

Retry Event

POST /v1/webhooks/events/:id/retry

await iof.webhooks.retryEvent("evt_xyz");

Event Types

Contract Events

• contract.created
• contract.updated
• contract.activated
• contract.matured
• contract.closed

KYC Events

• kyc.submitted
• kyc.verified
• kyc.rejected
• kyc.expired

Compliance Events

• compliance.check.completed
• compliance.alert.triggered

Billing Events

• billing.invoice.created
• billing.invoice.paid

Delivery Status

Status	Description
pending	Awaiting delivery
delivered	Successfully delivered
failed	Delivery failed
retrying	Retry in progress

Retry Policy

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

Security

See Webhook Security for signature verification.

Next Steps

• Search Rail - Full-text search
• Security Guide - Signature verification