🧀Webhooks

Webhooks provide a way to receive notifications from Terraswitch for your transactions and API calls in real time. While your transaction is being processed, its status progresses until it is completed. This makes it very important to get the final status for that transaction, and that's where webhooks are very beneficial.

Described easily, a webhook URL is a "POST" request endpoint on your server that can receive API requests from Terraswitch platform. Note that the request is going to be an HTTP POST request.

💡Helpful Tip We recommend that you use webhook to provide value to your customers over using callbacks or polling. With callbacks, we don't have control over what happens on the customer's end and neither do you.

Events and notification types you can receive

• Successful completion of a "Pay-In" transaction

• Successful completion of a "Pay-Out" transaction

• Successful completion of a "VAS" transaction

• Receive notifications on your payment links when transactions are successful

When your webhook URL receives an event, it needs to parse and acknowledge the event. Acknowledging an event means returning a 200 OK in the HTTP response. Without a 200 OK in the response header, we’ll keep sending events for 24 hours.

Please note that you will receive notifications too when transactions fail based of events. Each event type will be specified and data structured properly for you.

Setting up your Webhook URL

You can specify your webhook URL in the API Keys page, a sub-page under the Settings page of your dashboard. Make sure that the webhook URL is unauthenticated and publicly available.

The request to the webhook URL comes with a payload, and this payload contains the details of the transaction for which you are being notified.

Setup your webhook URL here

Your webhook URL must return any of the standard HTTP success status codes the first time you are setting it up on your dashboard.

Verify webhook events origin

Since your webhook URL is publicly available, you need to verify that events originate from Terraswitch and not a bad actor. To verify event origin from Terraswitch, use the signature validation method. Events sent from Vacepay carry the x-terraswitch-signature header. The value of this header is a HMAC SHA512 signature of the event payload signed using your API key. Verifying the header signature should be done before processing the event payload.

Node.js

import crypto from 'crypto';
const API_KEY = process.env.TERRASWITCH_API_KEY;

// Using Express
app.post("/my/webhook/url", function(req, res, next) {
    
    const payload = req.body;
    const datastring = JSON.stringify(payload);
    const signature = req.headers['x-terraswitch-signature'];

    const hash = crypto
    .createHmac('sha512', `${API_KEY}`)
    .update(datastring)
    .digest('hex');

    if(hash === signature){
    
        // process payloand
        console.log(payload)
    
    }
    
    res.send(200);
});

Webhook go live checklist

• Add your webhook URL on your Terraswitch dashboard

• Ensure your webhook URL is publicly available (localhost URLs cannot receive events)

• If using .htaccess kindly remember to add the trailing / to the URL

• Test your webhook to ensure you’re getting the JSON body and returning a 200 OK HTTP response

• If your webhook function has long-running tasks, you should first acknowledge receiving the webhook by returning a 200 OK before proceeding with the long-running tasks

• If we don’t get a 200 OK HTTP response from your webhooks, we will flag it as a failed attempt

• Failed attempts are retried every 1 minute for the first 3 tries, then we switch to sending hourly for the next 24 hours

Supported webhook events

payin.success

// Some code

payin.failed

payin.link.success

payin.link.failed

payout.success

payout.failed

vas.success

vas.failed

more

Types of webhook events

Event Type	Description
payin.success	Your wallet was funded via your virtual account number
payin.failed	Funding on your wallet, via your virtual account number failed
payin.link.success	A payment was made using one of your active payment links
payin.link.failed	Payment via your payment link failed
payout.success	Withdrawal or transfer transaction from your wallet was successful
payout.failed	Withdrawal or transfer from wallet failed
vas.success	A VAS transaction on your wallet was successful. E.g. buy airtime
vas.failed	A VAS transaction (e.g. pay bill) on your account failed
refund.success	Initiated refund on your account was successful
refund.failed	initiated refund on your account eventually failed
chargeback.success	Accepted chargeback on your account was successful
chargeback.failed	Accepted chargeback failed eventually after processing