English
API ReferenceSign In

Setup Callback with Xendit in PHP and Cpanel

Last updated 10/27/2021

Welcome! This article will assist you to setup Xendit callback using PHP and CPanel.


In this article, we’ll cover what is callback/webhook, how callback/webhook work in Xendit, and how you can easily integrate Xendit callback to your system or application you’re building.


We will use Invoice / Checkout API as a tutorial example, but you can follow the same steps to set up callback for other Xendit products.

What is a callback? And How does it work?

Callback or webhook is a term commonly used in engineering to represent a function being called after. In this context, it means Xendit will call and fire a HTTP request to you (typically your url registered), typically when a payment has been processed successfully by Xendit, or refunded or failed, so your system can act accordingly based on the payment status.


The diagram below shows the simple explanation of how callback is interpreted.


Imagine you are a merchant or Xendit’s registered user. You are then building up your website to collect payment from customers. You initiate the integration with Xendit to accept payments via Invoice API.


First, you’ll call Invoice API to create an Invoice for your customer upon checkout. An Invoice will be created and you can send the Invoice link or embed the QR code to your customer to complete payment.


When your customer has finalized the Invoice payment, Xendit processes the payment and send an Invoice paid callback to your system, indicating an Invoice has been successfully paid, and you can proceed to ship your product or service to the buyer (or any business process you want to implement in your system).


Callback or Webhook is typically called Reverse API. Take a look at the illustration below to spot the difference in API vs webhook.



More explanations can be found here.


We have covered what is callback / webhook and how it works at Xendit. Let’s set up your Xendit account and see how to provide a callback URL to Xendit.

Signing up with Xendit and Setup your Callback


To own an account with xendit is super easy and free. With a few clicks, you will be set to go.


First, go to https://dashboard.xendit.co/register/1


Once you complete the registration process, you’ll be redirected to your dashboard.


If you are still unsure how to perform your first API call, this article “Making your First API Call with Xendit” will set you up in a quick glance. Once you have made your first call, it’s time for you to set up your callback URL. yay !


First, On your dashboard, click Settings.

You will then see this page


Next, click Callbacks as highlighted in the screenshot above.


Make sure you enable auto-retry for failed callback, by enabling this, you will have better experience in handling your callback response.


Next, is to obtain your callback verification token. Click View Callback Verification Token, Enter your password, and keep that token inside your server side. We’ll use this token to verify message authenticity, which will be explained in detail in code snippet below in Implementation section


Once all above are set, you have one last step to complete your callback setup, which is to set your callback URL. Next, you can fill up your URL handling for the callback under the Callback URL section according to your being used product with Xendit.


In this context, we will use Invoice as a journey example for your callback. In order for you to setup a callback, you must have a URL to listen to callback. In this example, I am using https://hendry-sukses.com/webhook.php as an example for your reference.



Once you have done, you can then click save and test. You might be seeing NO_RESPONSE, but do not worry. This is normal and expected, because you might not yet set the listener for the callback URL set, we’ll cover that later.


Create callback implementation on PHP Code or via CPANEL

You have registered an account with Xendit, made your first API call, set callback on callback setting. You’re ready to go for the next step, which is to implement the callback url listener.


Earlier, we have set the callback URL for the invoice events to https://hendry-sukses.com/webhook.php


Let’s start to write some PHP Code on webhook.php as the listener for invoice callback.

Assuming the domain is https://hendry-sukses.com and /webhook.php is the path where the callback will happen.


If you are using CPANEL, you may navigate to File Manager, and start creating new file by clicking on the + File


Once webhook.php is created, you can click Edit button, and you shall see below prompt. Make sure you choose utf-8 and click edit.



Once you click edit, you’ll be redirected to the online code editor by CPANEL.


As a PHP coder, we’ll always start by typing <?php :D, aren’t we?


Okay, let’s get to the real implementation. We are now going to write the listener at webhook.php which will expose to the domain http://hendry-sukses.com/webhook.php. Please ensure you have your domain ready, and able to expose your endpoint as a callback listener.


We have to ensure on the callback according to Xendit’s Callback Best Practice in terms of


Let’s get to work ! Please find the code snippet below for the basic implementation of the callback listener. I will explain what each line means afterwards.

<?php

// This will be your Callback Verification Token you can obtain from the dashboard.
// Make sure to keep this confidential and not to reveal to anyone.
// This token will be used to verify the origin of request validity is really from Xendit
$xenditXCallbackToken = 'Your Xendit Verification Callback Token Here';

// This section is to get the callback Token from the header request, 
// which will then later to be compared with our xendit callback verification token
$reqHeaders = getallheaders();
$xIncomingCallbackTokenHeader = isset($reqHeaders['x-callback-token']) ? $reqHeaders['x-callback-token'] : "";

// In order to ensure the request is coming from xendit
// You must compare the incoming token is equal with your xendit callback verification token
// This is to ensure the request is coming from Xendit and not from any other third party.
if($xIncomingCallbackTokenHeader === $xenditXCallbackToken){
  // Incoming Request is verified coming from Xendit
  // You can then perform your checking and do the necessary, 
  // such as update your invoice records
    
  // This line is to obtain all request input in a raw text json format
  $rawRequestInput = file_get_contents("php://input");
  // This line is to format the raw input into associative array
  $arrRequestInput = json_decode($rawRequestInput, true);
  print_r($arrRequestInput);
  
  $_id = $arrRequestInput['id'];
  $_externalId = $arrRequestInput['external_id'];
  $_userId = $arrRequestInput['user_id'];
  $_status = $arrRequestInput['status'];
  $_paidAmount = $arrRequestInput['paid_amount'];
  $_paidAt = $arrRequestInput['paid_at'];
  $_paymentChannel = $arrRequestInput['payment_channel'];
  $_paymentDestination = $arrRequestInput['payment_destination'];

  // You can then retrieve the information from the object array and use it for your application requirement checking
    
}else{
  // Request is not from xendit, reject and throw http status forbidden
  http_response_code(403);
}


Now we have done the first step by initiating the following action:

  • Setup listener callback URL
  • Write code implementation to listen to callback
  • Verify the origin identity of the request to match with Xendit Verification Token
  • Return response code once the process of listener ends. [ http_response_code(200) ]


And if you can see there’s a line print_r($arrRequestInput), we will then prove to see if the callback URL works and able to obtain the request being passed by Xendit callback to us.

Let’s try it out the code ;) through callback settings again.

Voila !!! Your made your first callback successfully 🥳 🥳 🥳 🥳 🥳


There’s so much more than meets the eye ! Same applies to this callback/webhook. You can perform lots of things on the callback such as:

  • Handling events of success or failure provisioning on your invoice or other services
  • Keeping logs to your own server to ease up easier troubleshooting
  • Handle duplicate events update, ensure your provisioning only happens once, and block if there’s more than one request


You are now all set !! We look forward to your successful integration with Xendit !!