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.

1. 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.

1. 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

```Text Bash node -v npm -v

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

```Text Bash
mkdir webhooks
touch webhook.js

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

```Text Javascipt 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

```Text Bash
npm install express body-parser

Start you node server

```Text Bash 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

```Text Bash
//create folder ngrok
mkdir ngrok

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

Expose your local server to the public internet

```Text Bash ./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

```php
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. Examples are shown in JSON format. Webhooks may require parsing.