Webhooks

Listen for events on your PiedPay account to automatize the integration of your business.

Configure methods

PiedPay offers these two ways to configure the URL address for receiving callback notifications.

Fixed configuration (Recommended)

Based on a Webhook endpoint URL, multiple events can be configured against it. The following are the currently supported webhook event types.

Event	Event Description
payment.succeeded	Occurs whenever a payment is succeeded.
payment.failed	Occurs whenever a payment is failed.
refund.succeeded	Occurs whenever a refund is succeeded.
mandate.succeeded	Occurs whenever a mandate is succeeded.
mandate.canceled	Occurs whenever a mandate is canceled.
subscription.created	Occurs whenever a subscription is created.
subscription.canceled	Occurs whenever a subscription is canceled.
subscription.completed	Occurs whenever a subscription is completed.

Dynamic configuration

For some objects(Payment, Refund, Mandate only) that support the notify_url parameter, it is allowed to send a callback URL on this parameter, for which PiedPay will send notifications on all events triggered. If notify_url is specified, no webhooks will be sent to webhook endpoint URL. Only https URLs are supported in livemode mode.

It is strongly recommended that this parameter is only applicable to debugging scenarios.

Retry Schedule

PiedPay webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. If PiedPay doesn’t quickly receive a 2xx response status code for an event, we would try to send it to your endpoint several more times until 2xx response is returned.

The retry backoff strategy is 5s, 10s, 2min, 5min, 10min, 30min, 1h, 2h, 6h, and 12h. Totally 10 times at most.

Sample Webhook Event Data

{
    "object": "event",
    "livemode": true,
    "type": "subscription.created",
    "data": {
        "object": {
            "id": "sub_Sq1e1OqvnP8CmzbP",
            "object": "subscription",
            "livemode": true,
            "reference": null,
            "customer_id": "cst_mDqj5S5CiXDCrbPi",
            "email": "test@customer.com",
            "mandate_id": "mdt_XfLSSGyDC8041aPi",
            "amount": "2.00",
            "currency": "USD",
            "description": "test",
            "time_created": "2022-09-19T15:00:13+08:00",
            "time_start": "2022-09-19T15:00:13+08:00",
            "time_current_period_start": null,
            "time_current_period_end": null,
            "interval_unit": "day",
            "times": 3,
            "times_completed": 0,
            "extra": {},
            "metadata": {},
            "status": "created"
        }
    },
    "request": "iar_b1CCi9W9GmfPOmjfP44a1Wb5",
    "account": "acct_yz50aD",
    "time_created": "2022-10-25T09:49:09+08:00"
}

Verifying Signatures

To make sure that the webhook message you receive is actually from PiedPay, you need to verify its signature. The methods are as follows:

1. First get the signature value in the PiedPay-Signature header.
2. Get webhook event data as payload message data, should be in JSON format.
3. Compute an HMAC with the SHA256 hash function, use the webhook endpoint’s signing secret as the key(For dynamical notify_url, use API key as signing secret), and use the payload string as the message.
4. Compare the signatures.

e.g.

$signature = \hash_hmac('sha256', $payloadInJson, $signingSecret);

Best Practices

PiedPay will try its best to push webhooks, but we can't rule out a few cases that can't be delivered in time, so please make sure to interface with the Retrieve interface and call it according to the reasonable time interval of the business itself, in order to make sure to get the final transaction result.