Skip to main content

​
Why should I use webhooks?

Pandabase webhooks can help you build real-time systems and facilitate payment acceptance. If you intend to provide something to a user immediately after a purchase, you can leverage webhook events.

​
Event Overview

We generate event data and send it to your webhook. There are different event types as mentioned in events. For example, when a payment is completed successfully, a payment.success event is sent to your endpoint with the order and transaction data. We automatically send this immediately once a resource is updated in our system.

​
The event object payload

Every webhook delivery is a JSON POST request with the following structure: 
{
  "object": "payment",
  "event": {
    "type": "payment.success",
    "id": "ord_abc123",
    "created_at": 1707400000000,
    "data": {
      "order": {
        "id": "ord_abc123",
        "order_number": "inv_xyz789",
        "status": "PROCESSING",
        "amount": 2999,
        "currency": "USD",
        "gateway": "STRIPE",
        "custom_fields": []
      },
      "transaction": {
        "id": "txn_def456",
        "transaction_id": "pi_stripe_xxx",
        "status": "SUCCESS",
        "amount": 3199,
        "fee": 200,
        "currency": "USD",
        "method": "STRIPE"
      }
    }
  }
}

​
Headers

Every webhook delivery includes the following headers:
HeaderDescription
X-Pandabase-SignatureHMAC-SHA256 hex digest of the JSON body, signed with your webhook secret
X-Pandabase-TimestampUnix timestamp (milliseconds) of when the delivery was sent
X-Pandabase-IdempotencyUnique delivery identifier for deduplication

​
Retries

We retry up to 5 times, with each attempt delayed using exponential backoff starting at 1 second. If we receive a 2xx status from your application, we mark the delivery as successful. Any other status code or a timeout (15 seconds) is treated as a failure and triggers a retry.

​
Verification

To ensure security, always verify webhooks. Webhooks can be verified to ensure they were actually sent by Pandabase and not by a malicious entity. To verify a webhook, you will need your webhook secret to confirm the SHA256 HMAC signature. Check the X-Pandabase-Signature header in the webhook request headers. Here are several examples: 
import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function validateSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-pandabase-signature"] as string;

  if (!signature) return res.status(401).send("Missing signature");

  try {
    const expected = crypto
      .createHmac("sha256", process.env.PANDABASE_WEBHOOK_SECRET!)
      .update(JSON.stringify(req.body))
      .digest("hex");

    const valid = crypto.timingSafeEqual(
      Buffer.from(signature, "hex"),
      Buffer.from(expected, "hex")
    );

    if (valid) {
      next();
    } else {
      res.status(401).send("Invalid signature");
    }
  } catch {
    res.status(401).send("Invalid signature");
  }
}

export { validateSignature };
This code calculates the HMAC signature by hashing the raw JSON body of the webhook payload using the SHA256 algorithm and your webhook secret. The result is compared against the X-Pandabase-Signature header to verify authenticity.