Webhook Documentation

Introduction

TransactAPI has webhooks which help you get notifications when TransactAPI methods respond with success. By using these webhooks, this alleviates the need to request a "get" method continuously to check on a status.

What is an webhook?

A webhook (also called a web callback or HTTP push API) is a way to exchange real-time information and updates automatically within two systems. Webhooks receive calls through HTTP POST requests only when the connected external system has a data update. APIs will place calls for data whether there's been a data update response, or not. This makes webhooks much more efficient for both provider and consumer.
While webhooks are an effective tool, they require an Internet connection between the data source and the web server to function. Additionally, a script must be present on the server at the destination URL and it must be able to recognize and parse the POST data. If the Internet connection or script is not available, the webhook will not work.

Creating webhooks and notifications

To create a webhook:

1. Navigate to the TransactAPI admin panel. On the Dashboard pane find the "View Webhooks" quick link. it it located under the "Administrative" section.

2. On the webhook page select the "Add Webhook" button in the top left corner. In the popup box select the webhook trigger you want. For example if you want you webhook to run when an account is created choose "createAccount". Then add your URL, this should be a URL that you have setup to listen for a POST method. If you have not used webhooks before we recommend using ngrok to setup a temporary URL for testing.

3. Your code should be listening for POST requests. Here is an example using ngrok and Node.js.

Check that node.js and npm are installed on your machine

node -v
npm -v

Create a new folder called webhooks. Then create a new file called webhooks.js

mkdir webhooks
touch webhook.js

Add this node.js code to you webhooks/webhook.js file

const express = require("express");
const bodyParser = require("body-parser");
const app = express();
const port = 3000; // Replace this with the port you want to use

// Middleware to parse incoming request data as JSON
app.use(bodyParser.urlencoded());

// Route to handle the 'getAccount' webhook method
app.post("/", (req, res) => {
  // Process the incoming webhook data for 'createAccount' method here
  // The data sent by TransactAPI will be available in req.body
  // You can access specific properties like req.body.accountId, req.body.accountType, etc.

  // For simplicity, we'll just log the received data
  console.log('Received "createAccount" webhook data:', req.body);

  // Respond to the webhook request
  res.status(200).send('Webhook for "getAccount" received successfully');
});

// Start the server
app.listen(port, () => {
  console.log(`Webhook server is running on port ${port}`);
});

Install Express and Body Parser

npm install express body-parser

Start you node server

node webhook.js

You should see a message indicating that the server is running, for example: Webhook server is running on port 3000

Now navigate to https://ngrok.com/ and signup for a free account

Copy your authtoken then create a new folder called ngrok and set your auth token.

After signing up, download the ngrok executable for your operating system (Windows, macOS, or Linux)

Create a new folder called ngrok

Put the downloaded executable file in the ngrok folder

In the ngrok folder authenticate you account

//create folder ngrok
mkdir ngrok

//authenticate your ngrok account
cd ngrok
./ngrok authtoken YOUR_AUTH_TOKEN

Expose your local server to the public internet

./ngrok http PORT_NUMBER

After running the ngrok http command, ngrok will generate a temporary public URL, which you can use to access your local server from the internet.
Look for the "Forwarding" section in the ngrok terminal output. You will see a URL in the format http://xxxxxx.ngrok-free.app. This URL is your temporary public address

Now you can navigate to the TransactAPI admin website and add your new URL "http://xxxxxx.ngrok-free.app" as the "Webhook URL 1" in the popup that appears when hit "AddWebhook". Don't forget to set you trigger method to "createAccount"

Now use the method of your choice (Postman, Custom Code, Admin Panel, etc...) to call the createAccount API endpoint. When that endpoint completes you will see your logs in the Node.js logs that we setup earlier.

Some sample PHP code

if ($conn->connect_error) 
    {
    die("Connection failed: " . $conn->connect_error);
                                                       
    }
if (isset($_POST['partyId'])) 
    {
    $partyId = $_POST['partyId'];
    $offeringId = $_POST['offeringId'];
    $orderStatus = $_POST['orderStatus'];
    $insert = mysqli_query($conn, "INSERT INTO checkworld (partyId,offeringId,orderStatus) VALUES ('$partyId','$offeringId','$orderStatus')") 
    or die(mysqli_error($conn));
    print_r($insert);
    }

You can also make these triggers send you emails or text messages

Just find the "View Notifications List" quick link on the Dashboard Pane and navigate to the Notifications page. Then click the "Add Notification" Button in the top left corner and add and email and phone number you would like to receive notifications at.

Webhook Method List

Below is the complete list of webhook methods available in the TransactAPI.