WooshPay Webhooks

WooshPay uses webhooks to make a server-to-server call to your server when an event occurs. Webhooks are particularly useful for asynchronous events like when a customer’s bank confirms a payment, a customer disputes a charge, or when collecting subscription payments.

The key attributes of a webhook are urland enabled_events
url To which Wooshpay sends an http request
enabled_events An event coresponds to transaction creation or status change. You specify those events that you'd like to be notifed.

You need to create webhooks for test and live environment separately. A webhook is active once created, and works for all your ongoing and following transactions. Please notice that your server would be notified for each active webhook you created, so to avoid duplicate notifications please do not create a same webhook multiple times.

Steps to Create and Receive Webhooks

You can start receiving event notifications in your app using the steps in this section:

1. Identify the events you want to monitor and the events payloads to parse.
2. Create a webhook endpoint as an HTTP endpoint (URL) on your local server.
3. Handle requests from WooshPay by parsing each event object and returning 2xx response status codes.
4. Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
5. Register your publicly accessible HTTPS URL by webhook object.

How to create a webhook endpoint

Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTP or HTTPS endpoint on your server with a URL. If you’re still developing your endpoint on your local machine, it can be HTTP. After it’s publicly accessible, it must be HTTPS.

Step 1. Identify the events to monitor

Use the API reference guide to identify the Wooshpay events and their event objects your webhook endpoint needs to parse.

Step 2: Create a webhook

Set up an HTTP endpoint on your local machine that can accept unauthenticated webhook requests with a POST method.

Request

{
    "url": "https://apitest.wooshpay.com/v1/receives",
    "description": "I am description",
    "enabled_events": [
        "payment_intent.created",
        "payment_intent.payment_failed",
        "payment_intent.requires_action",
        "payment_intent.succeeded",
        "payment_intent.canceled",
        "charge.refund.updated"
    ],
    "api_version": "1.0.1"
}

Response

{
    "id": "we_1600745739909070848",
    "object": "webhook_endpoint",
    "created": 1670482499000,
    "description": "I am description",
    "metadata": null,
    "secret": "c2tfdGVzdF9kR1Z6ZERwMFpYTjBNVEl6TkRVMjo=",
    "status": "enabled",
    "url": "https://apitest.wooshpay.com/v1/receives",
    "livemode": false,
    "api_version": "1.0.1",
    "enabled_events": [
        "payment_intent.created",
        "payment_intent.payment_failed",
        "payment_intent.requires_action",
        "payment_intent.succeeded",
        "payment_intent.canceled",
        "charge.refund.updated"
    ]
}

Step 3: Handle requests from WooshPay

Your endpoint must be configured to read event objects for the type of event notifications you want to receive. WooshPay sends events to your webhook endpoint as part of a POST request with a JSON payload.

Return a 2xx response
Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout.

Delivery attempts and retries

Understand how to view delivery attempts, event logs, and the retry logic when webhook events aren’t acknowledged.

Retry logic
In live and test mode, WooshPay attempts to deliver your webhooks for up to three days with an exponential back off, which means in total we will deliver 18 times in 72 hours.

Pending Webhook logic
In live and test mode, WooshPay will attempt to notify you of any unsuccessful webhooks via email if an endpoint has not responded with a 2xx HTTP status code. The email will not only tell you the URL that cannot be delivered, but also when we will stop deliver the webhooks, and also the best way for you to reach us.

What the event your server receive looks like

Below is the json structure of an event, which is also the http body your server receives.
This is a payment_intent.succeeded event.

{
    "id": "evt_1705940809180720000",
    "object": "event",
    "created": 1702715524825,
    "livemode": false,
    "data": {
        "object": {
            "id": "pi_17059408432822016",
            "object": "payment_intent",
            "created": 1702715520000,
            "livemode": true,
            "currency": "EUR",
            "amount": 6838,
            "status": "succeeded",
            "metadata": {
                "pay_no": "6222623493518490"
            },
            "merchant_order_id": "6222623493518490",
            "client_secret": "pi_17359408432822016_secret_1NFdn5Rsfm0udwLIaWnK",
            "payment_method_types": [
                "card"
            ],
            "confirmation_method": "automatic",
            "payment_method_options": {
                "card": {
                    "client": "android",
                    "request_three_d_secure": "void"
                }
            },
            "return_url": "https://pay.fordddd.com/v1/payment/redirect/wooshpay/622262349473518490",
            "payment_method": "pm_17359484348464",
            "amount_received": 6838,
            "capture_method": "automatic"
        }
    },
    "type": "payment_intent.succeeded"
}