WooshPay Webhooks #

WooshPay uses webhooks to notify your application when an event happens in your account. 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. You can configure webhook endpoints via the API to be notified about events.

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.