Webhooks API

Manage webhook endpoints for event notifications.

Create Webhook

Register a new webhook endpoint.

POST /api/webhooks

Request

{
  "url": "https://yoursite.com/webhooks/zkp2p",
  "events": ["order.fulfilled", "order.failed"]
}

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint URL
events	string[]	No	Events to subscribe to (empty = all)

Response

{
  "success": true,
  "responseObject": {
    "id": "wh_abc123",
    "merchantId": "merch_xyz789",
    "url": "https://yoursite.com/webhooks/zkp2p",
    "events": ["order.fulfilled", "order.failed"],
    "active": true,
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0...",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

caution

The secret is only returned once. Store it securely for signature verification.

---

List Webhooks

Get all webhooks for your merchant account.

GET /api/webhooks

Response

{
  "success": true,
  "responseObject": {
    "webhooks": [
      {
        "id": "wh_abc123",
        "merchantId": "merch_xyz789",
        "url": "https://yoursite.com/webhooks/zkp2p",
        "events": ["order.fulfilled", "order.failed"],
        "active": true,
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

---

Get Webhook

Get a specific webhook.

GET /api/webhooks/:id

Response

{
  "success": true,
  "responseObject": {
    "id": "wh_abc123",
    "merchantId": "merch_xyz789",
    "url": "https://yoursite.com/webhooks/zkp2p",
    "events": ["order.fulfilled", "order.failed"],
    "active": true,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

---

Update Webhook

Update a webhook's configuration.

PATCH /api/webhooks/:id

Request

{
  "url": "https://newurl.com/webhooks",
  "events": ["order.fulfilled"],
  "active": true
}

All fields are optional. Only provided fields are updated.

Response

{
  "success": true,
  "responseObject": {
    "id": "wh_abc123",
    "url": "https://newurl.com/webhooks",
    "events": ["order.fulfilled"],
    "active": true,
    ...
  }
}

---

Delete Webhook

Delete a webhook.

DELETE /api/webhooks/:id

Response

{
  "success": true,
  "message": "Webhook deleted successfully"
}

---

Test Webhook

Send a test event to verify your endpoint.

POST /api/webhooks/:id/test

Response

{
  "success": true,
  "responseObject": {
    "success": true,
    "deliveryId": "del_xyz789",
    "responseCode": 200
  }
}

If the test fails:

{
  "success": true,
  "responseObject": {
    "success": false,
    "deliveryId": "del_xyz789",
    "responseCode": 500,
    "error": "Connection refused"
  }
}

---

List Deliveries

Get delivery history for a webhook.

GET /api/webhooks/:id/deliveries

Response

{
  "success": true,
  "responseObject": {
    "deliveries": [
      {
        "id": "del_abc123",
        "webhookId": "wh_xyz789",
        "eventType": "order.fulfilled",
        "eventId": "evt_123456",
        "status": "DELIVERED",
        "attempts": 1,
        "lastAttemptAt": "2024-01-15T10:00:00.000Z",
        "responseCode": 200,
        "createdAt": "2024-01-15T10:00:00.000Z"
      },
      {
        "id": "del_def456",
        "webhookId": "wh_xyz789",
        "eventType": "order.failed",
        "eventId": "evt_789012",
        "status": "FAILED",
        "attempts": 8,
        "lastAttemptAt": "2024-01-16T10:00:00.000Z",
        "responseCode": 500,
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

---

Available Events

Event	Description
order.created	Order created, intent signaled
order.payment_sent	User sent fiat payment
order.fulfilled	Payment complete
order.failed	Payment failed
order.expired	Order expired
session.started	Checkout started
session.completed	Checkout completed
session.abandoned	Checkout abandoned

See Webhook Events for detailed payload information.