Skip to main content

Webhook Setup

Set up webhooks to receive real-time event notifications.

Creating a Webhook​

Create a webhook using the Webhooks API:

curl -X POST https://api.zkp2p-pay.xyz/api/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "url": "https://yoursite.com/webhooks/zkp2p",
    "events": ["order.fulfilled", "order.failed"]
  }'

Response:

{
  "success": true,
  "responseObject": {
    "id": "wh_abc123",
    "merchantId": "merchant_xyz",
    "url": "https://yoursite.com/webhooks/zkp2p",
    "events": ["order.fulfilled", "order.failed"],
    "active": true,
    "secret": "whsec_a1b2c3d4e5f6...",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}
Store Your Secret

The secret is only returned once when the webhook is created. Store it securely - you'll need it to verify webhook signatures.

Subscribing to Events​

You can subscribe to specific events or receive all events:

// Subscribe to specific events
{
  "url": "https://yoursite.com/webhooks",
  "events": ["order.fulfilled", "order.failed", "order.expired"]
}

// Subscribe to all events (empty array or omit events)
{
  "url": "https://yoursite.com/webhooks",
  "events": []
}

Endpoint Requirements​

Your webhook endpoint must:

  1. Accept POST requests with JSON body
  2. Respond with 2xx status within 30 seconds
  3. Be publicly accessible (no localhost in production)
  4. Use HTTPS (required for production)

Basic Endpoint Example​

import express from 'express';

const app = express();

// Use raw body for signature verification
app.post(
  '/webhooks/zkp2p',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    // Verify signature first (see Verification docs)

    const event = JSON.parse(req.body.toString());

    console.log('Received event:', event.type);
    console.log('Event ID:', event.id);

    // Respond immediately
    res.status(200).send('OK');

    // Process async
    processEvent(event).catch(console.error);
  }
);

async function processEvent(event) {
  switch (event.type) {
    case 'order.fulfilled':
      // Handle successful payment
      break;
    case 'order.failed':
      // Handle failed payment
      break;
  }
}

Managing Webhooks​

List Webhooks​

curl https://api.zkp2p-pay.xyz/api/webhooks \
  -H "X-API-Key: your_api_key"

Update Webhook​

curl -X PATCH https://api.zkp2p-pay.xyz/api/webhooks/wh_abc123 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "url": "https://newurl.com/webhooks",
    "events": ["order.fulfilled"],
    "active": true
  }'

Delete Webhook​

curl -X DELETE https://api.zkp2p-pay.xyz/api/webhooks/wh_abc123 \
  -H "X-API-Key: your_api_key"

Test Webhook​

Send a test event to verify your endpoint:

curl -X POST https://api.zkp2p-pay.xyz/api/webhooks/wh_abc123/test \
  -H "X-API-Key: your_api_key"

Viewing Delivery History​

Check the delivery status of webhooks:

curl https://api.zkp2p-pay.xyz/api/webhooks/wh_abc123/deliveries \
  -H "X-API-Key: your_api_key"

Response includes delivery attempts, status codes, and retry information.