Getting Started

Ready to get started with Xendit webhooks? You can follow along with these directions, as we show you how to receive Xendit webhooks with your web application. This getting started guide is not specific to a certain product at Xendit or to a particular language or platform, so you can follow along and apply these across all products.

Find the right webhooks

The first step in the process is to find the right webhooks for your application. This depends on the Xendit products you’re using. The list of Xendit webhooks can be found here:

Of course, your project may not need all of these webhooks - but you may be able to add some interesting functionality by using them!

Responding to webhooks

The next step is to map out how you will respond to each webhook. We recommend you to respond to our webhook with status 200 immediately. If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before Xendit sees its complete execution. Ideally, your webhook handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that event.

INFO

We mark events as timeout/failed when there is no response for 30s

Use Mock Webhook Requests for development

Once you have identified the webhooks you are planning to use, it's time to write some code! For ad-hoc testing purposes during development, you may find it worthwhile to set up mock HTTP requests to your application. We suggest either using a command-line tool like curl, or a desktop application like Postman.

Use the sample webhook requests found in the Xendit API Reference as starters for your own requests, or send Xendit webhooks to a service like Webhook.site or RequestBin to capture the HTTP request being sent.

Example of eWallet webhook event payload. See other payload in API Reference

{
  "event": "ewallet.capture",
  "created": "2020-10-21T13:59:14.536400713Z",
  "business_id": "59e0daf7049b567510c63f67",
  "data": {
    "id": "ewc_95d47d3a-db03-4b4b-9b6c-71077157cbc8",
    "basket": null,
    "status": "SUCCEEDED",
    "actions": {
      "mobile_web_checkout_url": "",
      "desktop_web_checkout_url": "",
      "mobile_deeplink_checkout_url": "https://wsa.uat.wallet.airpay.co.id/universal-link/wallet/pay?deep_and_deferred=1&token=dFhkbmR1bTBIamhWwFfJaB-n_6eGjr1eAHnlwWEJDsEpIU_-8m0QS5Tb1nFp_ZEtGrgHWKV8LuV6rwVL2COCVw"
    },
    "created": "2020-10-21T13:57:43.355897Z",
    "updated": "2020-10-21T13:57:43.730483Z",
    "currency": "IDR",
    "metadata": {
      "branch_code": "senayan_372"
    },
    "voided_at": null,
    "capture_now": true,
    "customer_id": null,
    "callback_url": "https://webhook.site/5eebb675-6102-453a-a81c-de95fb08bc77",
    "channel_code": "ID_SHOPEEPAY",
    "failure_code": null,
    "reference_id": "test-payload",
    "charge_amount": 20000,
    "capture_amount": 20000,
    "checkout_method": "ONE_TIME_PAYMENT",
    "payment_method_id": null,
    "channel_properties": {
      "success_redirect_url": "https://google.com"
    },
    "is_redirect_required": true
  }
}

Run your application on a public URL

Xendit needs to send webhook requests to a publicly available URL. There are two main ways of approaching this - the first is to deploy your web application code to a development or test server that is reachable from the public internet. The second way is to use an HTTP tunneling tool like ngrok to set up a public URL for your application (like https://n3f6j25.ngrok.io/) that maps to a web application server running locally on your computer.

In some cases, ngrok or other http tunnels may be blocked by your internal network's firewalls. In those cases, you should set up a development or testing server to use with Xendit before deploying your webhook project to a production environment.

For more about using ngrok to turn your local environment to public URL easily, see these public tutorials:

  • MacOS. Credits to: Pentacode
  • Windows. Credits to: Awais Mirza

Configure your public URL with Xendit

Now, Xendit will need to know what URL to send webhooks to. You will need to set the Webhook URL either via Dashboard or API

Set URL via Dashboard

  1. Navigate to Webhook settings in Xendit Dashboard
  2. In Webhook section, find the product you are integrating with under Webhook URL section and save your webhook URL there
  3. We recommend creating a webhook URL based on the product that you are integrating with. If you’re integrating with Invoice API, then you should set the Invoice webhook URL, and same for other products
INFO

Save and Test feature will always save your URL regardless of test result

Set URL via API

You can also set your Webhook URL via API. Check out Set URL API Reference for further parameters detail. This API is especially useful for xenPlatftorm users to set Webhook URLs across their sub-accounts. Note that this can only be done for Managed sub-accounts. Owned sub-accounts share webhook settings with the Platform account.

  <?php
      $url = 'https://api.xendit.co/callback_urls';
      $apiKey = 'xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:';
      $headers = [];
      $headers[] = 'Content-Type: application/json';
      $data = [
          'url' => 'https://www.xendit.co/callback_catcher'
      ];

      $curl = curl_init();

      $payload = json_encode($data);
      curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
      curl_setopt($curl, CURLOPT_USERPWD, $apiKey.":");
      curl_setopt($curl, CURLOPT_URL, $url);
      curl_setopt($curl, CURLOPT_POST, true);
      curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
      curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

      $result = curl_exec($curl);
      echo $result;
?>

Validate that webhook requests are coming from Xendit

Once you have Xendit sending requests to your web application, you may start validating that your incoming webhooks are actually from Xendit. This ensures that third parties can't issue requests to your webhook URL.

Xendit attaches x-callback-token header when delivering webhook event to your system. Your x-callback-token will be unique to your account per environment, which you can validate the header against the token you can find in Webhook Settings. If the webhook contains token to your account, then you can accept it, and reject it if otherwise.

INFO

A Developer permission is required to access this page

Test your webhooks with live traffic

Everything should work now, but it's time to try some live traffic out! This will depend on which webhooks you are using, but you can start making a VA payment, expiring an Invoice, or whatever else you have built. Try to exercise as many corner or edge cases as possible with your application, so that you can see if there were any assumptions left out of your unit or integration tests. Go in and add those edge cases to your automated tests, while you are doing manual testing.

Promote your web application to Test and Live

Now you can start the process of promoting your web application to a Test environment, and then to Live. As you enter each step, update the webhook URL you use with Xendit in Live mode to ensure that the testing you are doing goes to the correct environment.

Double check that your Live Xendit URLs are pointing to production web application environments. Similarly, make sure that the webhooks are being received in production, and network rules don't need to be changed on the firewall.

Test your webhook with SSL enabled, and the certificates you use in production, to ensure that everything works correctly. Xendit webhooks will not work on HTTPS endpoints with self-signed SSL certificates

Congratulations! Your web application is in production, and ready to respond to Xendit webhooks! If you run into problems, please visit the Webhooks FAQ.


Last Updated on 2024-02-15