Webhooks API

Manage webhook endpoints for real-time event delivery from the ZexRail platform.

POST/v1/webhooks

Request Body

{
  "url": "https://example.com/webhooks/zexrail",
  "events": ["settlement.executed", "negotiation.accepted"],
  "secret": "whsec_your_signing_secret",
  "description": "Production settlement notifications"
}

Response

{
  "id": "wh-a1b2c3d4",
  "url": "https://example.com/webhooks/zexrail",
  "events": ["settlement.executed", "negotiation.accepted"],
  "status": "active",
  "createdAt": "2024-03-01T12:00:00Z"
}

Error Codes

Status	Reason
400	Invalid URL or unsupported event type
409	Webhook endpoint already registered for this URL

GET/v1/webhooks

List all webhook endpoints registered for your organization.

Response

{
  "data": [
    {
      "id": "wh-a1b2c3d4",
      "url": "https://example.com/webhooks/zexrail",
      "events": ["settlement.executed", "negotiation.accepted"],
      "status": "active",
      "successRate": 99.2,
      "lastDeliveredAt": "2024-03-10T15:30:00Z"
    }
  ]
}

Error Codes

Status	Reason
401	Invalid or missing API key

GET/v1/webhooks/:id

Retrieve detailed information about a webhook endpoint including delivery statistics.

Response

{
  "id": "wh-a1b2c3d4",
  "url": "https://example.com/webhooks/zexrail",
  "events": ["settlement.executed", "negotiation.accepted"],
  "status": "active",
  "description": "Production settlement notifications",
  "stats": {
    "totalDeliveries": 847,
    "successRate": 99.2,
    "averageLatency": "120ms",
    "lastDeliveredAt": "2024-03-10T15:30:00Z"
  },
  "createdAt": "2024-03-01T12:00:00Z"
}

Error Codes

Status	Reason
404	Webhook endpoint not found

PATCH/v1/webhooks/:id

Update a webhook endpoint configuration. You can change the URL, subscribed events, or status.

Request Body

{
  "events": ["settlement.executed", "settlement.failed", "negotiation.accepted"],
  "status": "active"
}

Response

{
  "id": "wh-a1b2c3d4",
  "url": "https://example.com/webhooks/zexrail",
  "events": ["settlement.executed", "settlement.failed", "negotiation.accepted"],
  "status": "active",
  "updatedAt": "2024-03-11T09:00:00Z"
}

Error Codes

Status	Reason
400	Invalid event type or status value
404	Webhook endpoint not found

DELETE/v1/webhooks/:id

Delete a webhook endpoint. Pending deliveries for this endpoint will be cancelled.

Response

{
  "id": "wh-a1b2c3d4",
  "deleted": true,
  "deletedAt": "2024-03-12T10:00:00Z"
}

Error Codes

Status	Reason
404	Webhook endpoint not found

POST/v1/webhooks/:id/test

Send a test event to a webhook endpoint to verify connectivity and signature validation.

Request Body

{
  "eventType": "settlement.executed"
}

Response

{
  "webhookId": "wh-a1b2c3d4",
  "testDelivery": {
    "status": "delivered",
    "responseCode": 200,
    "latency": "85ms",
    "signatureValid": true
  },
  "sentAt": "2024-03-11T09:05:00Z"
}

Error Codes

Status	Reason
400	Invalid event type for test
404	Webhook endpoint not found
502	Endpoint returned an error or timed out