Integration

Webhooks Integration Guide

Copy page

Overview

Webhooks allow SaligPay to notify your server about payment events in real-time. Instead of polling for status updates, your application receives instant notifications when payments complete, subscriptions activate, or refunds process.

How Webhooks Work

Code
 
Customer Pays → SaligPay Processes → Webhook Sent → Your Server Receives
                                              ↓
                                      Verify Signature
                                              ↓
                                      Process Event
                                              ↓
                                      Return 200 OK

Quick Start

Step 1: Set Up Webhook Endpoint

Code
 
import express from "express";
import { SaligPay } from "saligpay-node";

const app = express();
const saligpay = new SaligPay({
    webhookSecret: process.env.SALIGPAY_WEBHOOK_SECRET!,
});

// Use raw body for signature verification
app.use("/webhooks/saligpay", express.raw({ type: "application/json" }));

app.post("/webhooks/saligpay", async (req, res) => {
    try {
        const payload = saligpay.webhooks.constructEvent(req.body);

        switch (payload.status) {
            case "completed":
                console.log("Payment completed:", payload.externalId);
                // Update order, send email, etc.
                break;
            case "failed":
                console.log("Payment failed:", payload.externalId);
                break;
        }

        res.status(200).json({ received: true });
    } catch (error) {
        console.error("Webhook error:", error);
        res.status(400).json({ error: "Invalid webhook" });
    }
});

Step 2: Configure Webhook URL

Set your webhook URL when creating checkout sessions or payment intents:

Code
 
const checkout = await saligpay.checkout.create({
    // ... other fields
    webhookUrl: "https://yourapp.com/webhooks/saligpay",
});

Webhook Event Types

Payment Events

Event	Description
checkout.completed	Payment session completed successfully
checkout.failed	Payment session failed
checkout.expired	Payment session expired
payment_intent.succeeded	Payment intent succeeded
payment_intent.failed	Payment intent failed
refund.created	Refund was created

Subscription Events

Event	Description
subscription.activated	Subscription is now active
subscription.past_due	Payment failed, retry scheduled
subscription.unpaid	Failed after max retries
subscription.cancelled	Subscription cancelled
subscription.invoice.paid	Invoice payment succeeded
subscription.invoice.payment_failed	Invoice payment failed

Signature Verification

Always verify webhook signatures to ensure authenticity:

Code
 
import { createHmac } from "crypto";

function verifyWebhookSignature(
    payload: string,
    signature: string,
    secret: string
): boolean {
    const expectedSignature = createHmac("sha256", secret)
        .update(payload, "utf8")
        .digest("hex");

    return signature === expectedSignature;
}

app.post("/webhooks/saligpay", (req, res) => {
    const signature = req.headers["paymongo-signature"] as string;
    const payload = req.body.toString();

    if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
        return res.status(401).json({ error: "Invalid signature" });
    }

    // Process webhook
    res.status(200).json({ received: true });
});

SDK Reference

WebhookResource

Method	Description
constructEvent(payload)	Parse webhook body
constructVerifiedEvent(payload, signature, timestamp?)	Parse and verify webhook
verifySignature(payload, signature, timestamp?)	Verify HMAC signature
listen(req, res, handler)	Express middleware handler
process(payload, handler)	Manual processing

Express Handler

Code
 
app.post("/webhooks/saligpay", async (req, res) => {
    await saligpay.webhooks.listen(req, res, async (payload) => {
        console.log("Webhook received:", payload);

        switch (payload.status) {
            case "completed":
                await db.orders.update(payload.externalId, { status: "PAID" });
                break;
            case "failed":
                await db.orders.update(payload.externalId, { status: "FAILED" });
                break;
        }
    });
});

Fastify Handler

Code
 
fastify.post("/webhooks/saligpay", async (request, reply) => {
    try {
        const payload = saligpay.webhooks.constructEvent(request.body);
        console.log("Payment:", payload.externalId, payload.status);
        return reply.send({ received: true });
    } catch (error) {
        return reply.code(400).send({ error: "Invalid webhook" });
    }
});

Best Practices

• Return 200 OK quickly; process events asynchronously
• Implement idempotency using event IDs to handle duplicates
• Verify webhook signatures on every request
• Log all webhook events for debugging
• Handle unknown event types gracefully
• Use HTTPS for webhook endpoints

---

Related Guides:

• Checkout Guide - For payment webhooks
• Subscription Guide - For subscription webhooks
• SDK Webhooks - For SDK method details