WooshPay OpenAPI
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Back to WooshPay Website
  1. After the payment
  • Online payments
    • Quick Start
    • Integration overview
    • Wooshpay JS SDK
    • Wooshpay Checkout
    • Wooshpay Direct API
    • Payment Link
    • Authorize and capture
    • Build subscriptions integration
    • Testing cards
  • After the payment
    • Payouts
    • Webhook
    • Check the webhook signatures
    • 校验webhook签名
  • Add more payment methods
    • Supported payment method
    • Cards
    • Wallets
      • Alipay
      • Alipay HK
      • Apple Pay
      • Google Pay
      • Wechat Pay
      • 微信支付
      • Kakao Pay
      • DANA
      • Boost
      • Grabpay
      • Mcash
      • Touch'n Go
      • ShopeePay
      • UnionPay
      • 9Pay
      • OVO
      • GCash
      • TrueMoney
    • Bank redirects
      • Bancontact
      • BPI
      • Trustly
      • EPS
      • Giropay
      • iDEAL
      • Przelewy24
      • FPX
    • Buy Now Pay Later
      • Klarna
    • Bank Debits
      • Sepa Direct Debit
    • Bank Transfer
      • Bank Transfer in Europe
      • Bank Transfer in United Kingdom
      • Bank Transfer in Indonesia
    • QR Payments
      • QRIS
      • PromptPay
    • Real-time payments
      • PIX
      • PayNow
      • UPI
      • SPEI
  • More payment scenarios
    • Set up future payments
    • Save payment method during payment
  • SaaS platform integration
    • Shopify Plugin
    • Shopastro 星盘
    • WooCommerce
    • Shoplazza 店匠
    • Shopline Plugin
    • Sage Connection
  • Resources
    • Supported currencies
  1. After the payment

Webhook

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"
}
Modified at 2024-01-25 09:28:28
Previous
Payouts
Next
Check the webhook signatures
Built with