📘
In a nutshell
Webhooks let you set up a notification system that automatically sends you updates when certain actions happen via the Pandascrow API — like payments, escrows, or account changes.

Introduction

Most times when you hit an API, you expect an instant response — success or failure, right away. But in some cases (like payment confirmations or long-running processes), that’s not always possible.

To avoid timeouts, we might return a pending response while the request continues processing in the background.

That’s where webhooks come in.

Webhooks let us notify your server once the final state of an event is known, like when a transaction is completed, a payment fails, or an escrow is updated. By setting up a webhook URL, your system stays in sync without needing to constantly poll our API.

Create a Webhook URL

<?php
// Set content type
header('Content-Type: application/json');

// Capture raw request body
$input = file_get_contents("php://input");
$event = json_decode($input, true);

// 1️⃣ Basic validation
if (!$event || !isset($event['event']) || !isset($event['data'])) {
    http_response_code(400);
    echo json_encode([
        'status' => false,
        'message' => 'Invalid payload structure'
    ]);
    exit;
}

// 2️⃣ Header checks
$receivedSignature = $_SERVER['HTTP_X_PANDASCROW_SIGNATURE'] ?? '';
$appKey            = $_SERVER['HTTP_X_PANDASCROW_APP'] ?? '';

// 3️⃣ Fetch your expected secret (this should match what Pandascrow uses)
$expectedSecret = 'sk_live_your_own_secret_key_here'; // You must replace this securely

// 4️⃣ Signature validation
$calculatedSignature = hash_hmac('sha256', json_encode([
    'event'     => $event['event'],
    'data'      => $event['data'],
    'timestamp' => $event['timestamp']
]), $expectedSecret);

if (!hash_equals($calculatedSignature, $receivedSignature)) {
    http_response_code(401);
    echo json_encode([
        'status' => false,
        'message' => 'Invalid signature'
    ]);
    exit;
}

// ✅ If passed, process the event
$eventType = $event['event'];
$payload   = $event['data'];

// You can now handle the event here...

// Respond to Pandascrow
http_response_code(200);
echo json_encode([
    'status' => true,
    'message' => 'Webhook received and processed successfully'
]);

// server.js
const express = require('express');
const crypto = require('crypto');

const app = express();
const PORT = 3000;

// Use raw body for signature verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString();
  }
}));

// Your secret key from Pandascrow dashboard
const EXPECTED_SECRET = 'sk_live_your_secret_key_here';

// Webhook endpoint
app.post('/webhook', (req, res) => {
  try {
    // Get headers
    const signature = req.headers['x-pandascrow-signature'];
    const appKey = req.headers['x-pandascrow-app'];
    
    // Get raw body (already saved via middleware)
    const rawBody = req.rawBody;
    const event = JSON.parse(rawBody);

    // 1️⃣ Basic validation
    if (!event || !event.event || !event.data) {
      return res.status(400).json({
        status: false,
        message: 'Invalid payload structure'
      });
    }

    // 2️⃣ Signature validation
    if (!signature) {
      return res.status(401).json({
        status: false,
        message: 'Missing signature'
      });
    }

    // Calculate expected signature
    // Pandascrow signs: event + data + timestamp
    const dataToSign = {
      event: event.event,
      data: event.data,
      timestamp: event.timestamp
    };

    const calculatedSignature = crypto
      .createHmac('sha256', EXPECTED_SECRET)
      .update(JSON.stringify(dataToSign))
      .digest('hex');

    // Compare signatures (timing-safe)
    if (!crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(calculatedSignature)
    )) {
      return res.status(401).json({
        status: false,
        message: 'Invalid signature'
      });
    }

    // 3️⃣ Process the event
    const eventType = event.event;
    const payload = event.data;

    console.log(`Received ${eventType} event:`);
    console.log(JSON.stringify(payload, null, 2));

    // Handle different event types
    switch(eventType) {
      case 'escrow.created':
        // New escrow created
        handleEscrowCreated(payload);
        break;
        
      default:
        console.log(`Unhandled event type: ${eventType}`);
    }

    // 4️⃣ Respond to Pandascrow
    res.status(200).json({
      status: true,
      message: 'Webhook received and processed successfully'
    });

  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({
      status: false,
      message: 'Internal server error'
    });
  }
});

// Event handlers
function handleEscrowCreated(payload) {
  // payload contains: escrowId, amount, currency, buyerEmail, sellerEmail, etc.
  console.log('New escrow created:', payload.escrowId);
  // Update your database, send notifications, etc.
}

// Start server
app.listen(PORT, () => {
  console.log(`Webhook server running on http://localhost:${PORT}`);
  console.log(`Webhook endpoint: http://localhost:${PORT}/webhook`);
});

📩 Receiving & Acknowledging Webhooks

When your webhook URL receives an event from Pandascrow, your system should do two things:

Parse the event payload
Acknowledge receipt by responding with a status true meaning (OK)

⚠️ If we don't receive a True (OK), we’ll assume delivery failed and retry for up to 72 hours.

🔁 Retry Behavior

Live Mode
- First 4 retries: every 3 minutes
- Afterwards, once every hour for the next 72 hours
Test Mode
- Retries occur hourly for up to 72 hours

🛡️ Verifying Event Origin

Because your webhook URL is publicly accessible, it’s critical to confirm that incoming events are genuinely from Pandascrow, not spoofed by third parties.

You can do this in two ways:

Signature Validation: Each event includes a signature header you can verify using your secret key. This ensures the event hasn’t been tampered with.
IP Whitelisting: Only accept requests coming from Pandascrow’s IP ranges.

Implementing both is highly recommended for production systems.

Supported events

{
    "event": "escrow.paid",
    "data": {
        "escrow_id": 2,
        "escrow_type": "onetime",
        "escrow_data": {
            "_id": 2,
            "escrow_type": "onetime",
            "initiator_role": "seller",
            "title": "Purchase #123456729 from Store ABC",
            "description": "Purchase 20 Ton of metal",
            "currency": "NGN",
            "amount": "350.00",
            "amount_pay": "350.00",
            "amount_receive": "341.25",
            "inspection_period": 1,
            "no_reviews": 1,
            "delivery_date": "2025-11-06",
            "how_dispute_is_handled": "platform",
            "who_pay_fees": "seller",
            "dispute_window": 5,
            "initiator_id": "a49882d5-041c-49f7-9bee-83ef86aa9b90",
            "receiver_id": "291a18b4-f074-42f5-998d-7f2e2a18d96f",
            "broker_id": null,
            "prd_url": "",
            "acceptance_criteria": "Hello world, this is an acceptance criteria xoxo",
            "deposit_option": "full",
            "callback_url": "app.wiserlance.com\/success",
            "partner_escrow_fee": "0.00",
            "status": "funded",
            "created_at": "2026-02-16 15:52:24",
            "updated_at": "2026-02-16 16:05:38"
        },
        "transaction": {
            "_id": 2,
            "escrow_id": 2,
            "user_id": "a49882d5-041c-49f7-9bee-83ef86aa9b90",
            "milestone_id": null,
            "type": "fund",
            "amount": "350.00",
            "amount_pay": "350.00",
            "amount_receive": "341.25",
            "currency": "NGN",
            "status": "success",
            "payment_url": "https:\/\/checkout.paystack.com\/w05phx8ia6y3eaj",
            "provider": "paystack",
            "transaction_ref": "fjjqemac4g",
            "domain": "test",
            "channel": "card",
            "ip_address": "127.0.0.1",
            "authorization_code": "AUTH_1e3rnb81by",
            "bin": "408408",
            "last4": "4081",
            "exp_month": "12",
            "exp_year": "2030",
            "card_type": "visa ",
            "bank": "TEST BANK",
            "country_code": "NG",
            "signature": "SIG_0jfBFo9zdvDO8gEFOX9w",
            "cust_name": "Pandascrow Buyer",
            "cust_email": "pandascrowhq.buyer@gmail.com",
            "created_at": "2026-02-16 15:52:30",
            "updated_at": "2026-02-16 16:07:23"
        },
        "buyer": {
            "_id": 4,
            "escrow_id": 2,
            "user_id": "291a18b4-f074-42f5-998d-7f2e2a18d96f",
            "name": "Pandascrow Buyer",
            "email": "pandascrowhq.buyer@gmail.com",
            "phone": "+2348098765432",
            "role": "receiver",
            "joined_at": "2026-02-16 15:52:24"
        },
        "seller": {
            "_id": 3,
            "escrow_id": 2,
            "user_id": "a49882d5-041c-49f7-9bee-83ef86aa9b90",
            "name": "Precious Tom",
            "email": "devtom0x@gmail.com",
            "phone": null,
            "role": "initiator",
            "joined_at": "2026-02-16 15:52:24"
        },
        "gateway_data": {
            "event": "charge.success",
            "data": {
                "id": 5844280067,
                "domain": "test",
                "status": "success",
                "reference": "fjjqemac4g",
                "amount": 35000,
                "message": null,
                "gateway_response": "Successful",
                "paid_at": "2026-02-16T15:53:00.000Z",
                "created_at": "2026-02-16T15:52:30.000Z",
                "channel": "card",
                "currency": "NGN",
                "ip_address": "105.116.9.111",
                "metadata": {
                    "escrow_id": "2",
                    "user_id": "a49882d5-041c-49f7-9bee-83ef86aa9b90",
                    "provider": "paystack"
                },
                "fees_breakdown": null,
                "log": null,
                "fees": 525,
                "fees_split": null,
                "authorization": {
                    "authorization_code": "AUTH_1e3rnb81by",
                    "bin": "408408",
                    "last4": "4081",
                    "exp_month": "12",
                    "exp_year": "2030",
                    "channel": "card",
                    "card_type": "visa ",
                    "bank": "TEST BANK",
                    "country_code": "NG",
                    "brand": "visa",
                    "reusable": true,
                    "signature": "SIG_0jfBFo9zdvDO8gEFOX9w",
                    "account_name": null,
                    "receiver_bank_account_number": null,
                    "receiver_bank": null
                },
                "customer": {
                    "id": 317040401,
                    "first_name": null,
                    "last_name": null,
                    "email": "pandascrowhq.buyer@gmail.com",
                    "customer_code": "CUS_730cys763yiibdn",
                    "phone": null,
                    "metadata": null,
                    "risk_action": "default",
                    "international_format_phone": null
                },
                "plan": [],
                "subaccount": [],
                "split": [],
                "order_id": null,
                "paidAt": "2026-02-16T15:53:00.000Z",
                "requested_amount": 35000,
                "pos_transaction_data": null,
                "source": {
                    "type": "api",
                    "source": "merchant_api",
                    "entry_point": "transaction_initialize",
                    "identifier": null
                }
            }
        },
        "recurring_data": null
    },
    "timestamp": 1771258051
}