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 a 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, 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 your webhook to run when an account is created, choose "createAccount". Then add your URL. This should be a URL that you have set up to listen for a POST method. If you have not used webhooks before we recommend using ngrok to set up a temporary URL for testing.

   

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

Run a local listener¶

Check that Node.js and npm are installed on your machine:

node -v
npm -v

Create a new folder called webhooks, then create a file called webhook.js inside it:

mkdir webhooks
touch webhooks/webhook.js

Add this code to webhooks/webhook.js:

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 your Node.js server:

node webhooks/webhook.js

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

Expose the listener with ngrok¶

1. Navigate to ngrok.com and sign up for a free account.
2. Download the ngrok executable for your operating system (Windows, macOS, or Linux).
3. Create a new folder called ngrok and put the downloaded executable in it.

4. Copy your authtoken from the ngrok dashboard, then authenticate from inside that folder:

   mkdir ngrok
   cd ngrok
   ./ngrok authtoken YOUR_AUTH_TOKEN
   

5. Expose your local server to the public internet:

   ./ngrok http PORT_NUMBER
   

ngrok generates a temporary public URL. Look for the "Forwarding" section in the ngrok terminal output, where the URL takes the form http://xxxxxx.ngrok-free.app. That URL is your temporary public address.

Navigate back to the TransactAPI admin site and add that URL as "Webhook URL 1" in the popup that appears when you select "Add Webhook". Set your trigger method to "createAccount".

Now call the createAccount endpoint by whichever means you prefer, such as Postman, your own code, or the admin panel. When the call completes, the payload appears in the Node.js logs you set up earlier.

Receiving the payload in PHP¶

if ($conn->connect_error) {
    die('Connection failed: ' . $conn->connect_error);
}

if (isset($_POST['partyId'])) {
    $stmt = $conn->prepare(
        'INSERT INTO checkworld (partyId, offeringId, orderStatus) VALUES (?, ?, ?)'
    );
    $stmt->bind_param(
        'sss',
        $_POST['partyId'],
        $_POST['offeringId'],
        $_POST['orderStatus']
    );
    $stmt->execute();
}

Email and SMS notifications¶

These triggers can also send you emails or text messages. Find the "View Notifications List" quick link on the Dashboard pane and navigate to the Notifications page. Select the "Add Notification" button in the top left corner, then add the email address and phone number you want notifications sent to.

Identifying webhook traffic from North Capital¶

Every webhook request we send includes headers your infrastructure can use to identify it — for example to allowlist our traffic in a firewall or WAF instead of subjecting it to bot-prevention rules:

To generate a token:

1. Navigate to the TransactAPI admin panel and open the Webhook page.
2. In the "Webhook Identification Tokens" section, click "Generate Token".
3. Copy the token value into your firewall or WAF rule. The value shown on the page is exactly what arrives in the X-NC-Token header.

Tokens are shared per organization: webhooks delivered for all client IDs under your parent client carry the same tokens.

To rotate a token without downtime:

1. Generate a new token. Both tokens are now sent on every webhook, comma-separated, so match the header using a contains rule rather than exact equality.
2. Update your firewall rule to the new token.
3. Retire the old token from the same page.

A token grants no access to the TransactAPI. Treat it as a secret: your endpoint may require it and reject any request that arrives without it. Do not expose it in client-side code or in logs you share.

A token is a fixed value and is not derived from the request body, so it does not indicate whether a payload has been modified. Signed payloads are not currently supported. Webhook endpoints are required to use HTTPS, and North Capital verifies the endpoint's certificate on every delivery. Contact your North Capital representative if your integration requires signed payloads.

These headers are the preferred way to identify North Capital traffic. Payload encryption remains available for integrations that require the payload itself to be encrypted at the application layer.

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.