> For the complete documentation index, see [llms.txt](https://pingpay.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pingpay.gitbook.io/docs/pingpay-api/webhooks.md). # Webhooks Getting started with Pingpay webhooks. *** ### What are Webhooks? Pingpay Webhooks allow teams to listen to payment events and verify transactions on your application's backend in real-time. Webhook endpoints are created through the **Ping Merchant Dashboard**. Once created, you can manage them via the dashboard or programmatically through the API. In the dashboard, you can view and manage all webhook endpoints and see triggered events when payments are processed. *** ### Setting Up Webhooks Webhook endpoints must be created through the dashboard. Once created, you can manage them via the dashboard or API. #### Creating a Webhook Endpoint
* Navigate to **Developer** > **Webhooks** in the dashboard * Click **"Add Endpoint"** * Enter your webhook URL * Select the events you want to receive * Click **"Create Endpoint"** * **Save your signing secret** - you'll need this to verify webhook signatures Once created, the endpoint will have the following structure: ```json { "endpoint": { "id": "whe_1a2b3c4d5e6f", "url": "https://your-server.com/webhook", "events": ["payment.success", "payment.failed"], "active": true, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" }, "secret": "whsec_a1b2c3d4e5f6g7h8" } ``` **Important:** Save the `secret` value securely. You'll need it to verify webhook signatures. *** ### Webhook Events Pingpay currently supports the following webhook events: | Event Type | Description | | ---------------------------- | ------------------------------------------- | | `payment.pending` | Payment entered the pending state | | `payment.success` | Payment was successfully completed | | `payment.failed` | Payment failed or was refunded | | `checkout.session.completed` | Checkout session was completed | | `checkout.session.expired` | Checkout session expired without completion | *** ### Webhook Payload ```json { "id": "evt_9x8y7z6w5v4u", "type": "payment.pending", "resourceId": "pay_3t2s1r0q9p8o", "data": { "additionalProperty": "anything" }, "createdAt": "2024-01-15T10:35:00Z" } ``` Thee `data` field contains detailed information about the payment or checkout session. View the [API Reference](https://pay.pingpay.io/api) for complete payload schemas for each event type. *** ### Verify Webhook Signatures Pingpay provides signature verification for webhook requests to verify authenticity. You can verify these signatures to ensure requests are genuinely from Pingpay. ```javascript const crypto = require('crypto'); function verifySignature(payload, timestamp, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(`${timestamp}.${payload}`) .digest('hex'); return signature === expected; } // Express.js middleware example app.post('/webhook', (req, res) => { const signature = req.headers['x-ping-signature']; const timestamp = req.headers['x-ping-timestamp']; const payload = JSON.stringify(req.body); if (!verifySignature(payload, timestamp, signature, YOUR_SECRET)) { return res.status(401).send('Invalid signature'); } // Process webhook... res.status(200).send('OK'); }); ``` *** ### Managing Webhooks Webhook endpoints can be managed through the **Ping Merchant Dashboard** or programmatically via the **API**. #### Via Dashboard
Navigate to **Developer** > **Webhooks** in your dashboard. For each endpoint, you can: * **Send Test** - Send a test webhook to verify your endpoint is working * **Rotate Secret** - Generate a new signing secret * **Disable** - Temporarily disable the endpoint without deleting it * **Delete** - Permanently remove the endpoint * **View Event Logs** - See delivery history and status for all webhook events #### Via API Use the following API endpoints to manage webhooks programmatically: **List All Endpoints** ```bash curl https://pay.pingpay.io/api/webhooks/endpoints ``` Response: ```json /{ "endpoints": [ { "id": "whe_1a2b3c4d5e6f", "url": "https://your-server.com/webhook", "events": ["payment.success", "payment.failed"], "active": true, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } ] } ``` **Get a Specific Endpoint** ```bash curl https://pay.pingpay.io/api/webhooks/endpoints/whe_1a2b3c4d5e6f ``` Response: ```json { "endpoint": { "id": "whe_1a2b3c4d5e6f", "url": "https://your-server.com/webhook", "events": ["payment.success", "payment.failed"], "active": true, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } } ``` **Update an Endpoint** ```bash curl https://pay.pingpay.io/api/webhooks/endpoints/whe_1a2b3c4d5e6f \ --request PATCH \ --header 'Content-Type: application/json' \ --data '{ "url": "https://your-server.com/webhook", "events": ["payment.success", "payment.failed", "payment.pending"], "active": true }' ``` Response: ```json { "endpoint": { "id": "whe_1a2b3c4d5e6f", "url": "https://your-server.com/webhook", "events": ["payment.success", "payment.failed", "payment.pending"], "active": true, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T12:00:00Z" } } ``` **Delete an Endpoint** ```bash curl https://pay.pingpay.io/api/webhooks/endpoints/whe_1a2b3c4d5e6f \ --request DELETE \ --header 'Content-Type: application/json' \ --data '{}' ``` Response: ```json { "success": true } ``` **Rotate Signing Secret** ```bash curl https://pay.pingpay.io/api/webhooks/endpoints/whe_1a2b3c4d5e6f/rotate \ --request POST \ --header 'Content-Type: application/json' \ --data '{}' ``` Response: ```json { "endpoint": { "id": "whe_1a2b3c4d5e6f", "url": "https://your-server.com/webhook", "events": ["payment.success", "payment.failed"], "active": true, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T12:00:00Z" }, "secret": "whsec_newSecret9i8u7y6t" } ``` *** ### Viewing Event History You can view webhook events and delivery attempts through the **Dashboard** or via the **API**. #### Via Dashboard
Navigate to **Developer** > **Webhooks** in your merchant dashboard. For each webhook endpoint, you'll see: * **Event Logs** - Shows all webhook events triggered for this endpoint * **Delivery Status** - View the status of each delivery attempt (pending, success, failed) * **Delivery Details** - See response codes, response bodies, and timestamps for each attempt #### Via API Use the following API endpoints to retrieve webhook history programmatically: **List Webhook Events** ```bash curl https://pay.pingpay.io/api/webhooks/events ``` Response: ```json { "events": [ { "id": "evt_9x8y7z6w5v4u", "type": "payment.pending", "resourceId": "pay_3t2s1r0q9p8o", "data": { "additionalProperty": "anything" }, "createdAt": "2024-01-15T10:35:00Z" } ] } ``` **View Delivery Attempts** ```bash curl https://pay.pingpay.io/api/webhooks/deliveries ``` Response: ```json { "deliveries": [ { "id": "del_7u6t5s4r3q2p", "eventId": "evt_9x8y7z6w5v4u", "endpointId": "whe_1a2b3c4d5e6f", "status": "PENDING", "statusCode": 1, "responseBody": "OK", "attemptNumber": 1, "nextRetryAt": "2024-01-15T10:40:00Z", "createdAt": "2024-01-15T10:35:00Z", "completedAt": "2024-01-15T10:35:01Z" } ] } ``` Delivery Statuses: * `PENDING` * `SUCCESS` * `FAILED` **Get Available Event Types** ```bash curl https://pay.pingpay.io/api/webhooks/event-types ``` Response: ```json { "eventTypes": [ { "type": "payment.pending", "description": "Triggered when a payment enters the pending state" }, { "type": "payment.success", "description": "Triggered when a payment is successfully completed" }, { "type": "payment.failed", "description": "Triggered when a payment fails or is refunded" }, { "type": "checkout.session.completed", "description": "Triggered when a checkout session is completed" }, { "type": "checkout.session.expired", "description": "Triggered when a checkout session expires" } ] } ``` *** View the Webhooks in [API Reference](https://pay.pingpay.io/api) for further detailed endpoint documentation.