Webhooks

Our webhooks provide real-time notifications for your system to receive updates on the state of certain requests.

Webhook Events

The following webhook events are currently available. Additional events will be added as new actions are introduced.

Notification Delivery

Your webhook notification URL can only be provided currently upon initiation of your transactions.

{
    "event": "payment.outflow.successful" , // or "payment.outflow.sent"
    "data": {
		"id": "TPO_xJ8dTp8OOrUg",
  		"completionDate": "2024-11-21T10:15:00Z",
  		"destinationAmount": "985.00",
  		"destinationCurrency": "USD",
  		"feeAmount": "15.00",
  		"feeCurrency": "USD",
  		"creationDate": "2024-11-20T14:30:00Z",
  		"reference": "d8bf770ab6b7b429a7fa948e",
  		"sourceAmount": "1000.00",
  		"sourceCurrency": "USD",
  		"status": "successful", // or sent
  		"statusReason": "The payment was successfully processed.",
  }
}

Important: Webhook requests time out after 20 seconds and a response must be provided within this timeframe. If your webhook processing requires more time, it is strongly recommended that you employ asynchronous processing to handle the webhook event and return a response immediately.

Whitelist IP Addresses

HarpFi sends webhook notification requests from specific IP addresses. To receive webhook calls successfully, you must whitelist these IP addresses in your firewall or server configuration.

Note: Ensure that your webhook endpoint is accessible from these IP addresses. Requests from other IPs should be rejected for security purposes.

Verifying Webhook Requests

Before processing a webhook, strongly advise that you verify authenticity of the request.

Each webhook request includes the following headers:

1. x-verification-signature: This header contains an HMAC SHA256 signature of the request body (arranged in an ascending order from A - Z), signed with your webhook signing secret which can be retrieved from your dashboard.
2. x-notification-version: This header contains the version number of the webhook signature used for version control. The latest version is 1.0.0

import crypto from 'crypto';

// Using Express
app.post("/your-webhook-url", function(req, res) {
    // Verify that the request is from HarpFi
    const secret = 'your-webhook-signing-secret'

    // req.body is expected to be an object and ordered in ascending order (A-Z)
    const sortedBody = Object.keys(req.body || {})
        .sort()
        .reduce((acc, key) => {
            acc[key] = req.body[key];
            return acc;
        }, {});
    
    const requestPayload = JSON.stringify(sortedBody);
    const hmac = crypto.createHmac('sha256', secret);
    const hash = Buffer.from('sha256' + '=' + hmac.update(requestPayload).digest('hex'), 'utf8');
    
    if (hash == req.headers['x-verification-signature']) {
      // The request is legitimate
    const event = req.body;
    // Do something with event  
    } else {
      // The request is fraudulent
    }
    res.send(200);
});

Webhook Retries

If a webhook notification fails to deliver due to a timeout or any non-2xx response, the notification will be retried at an exponential schedule of 5m, 30m, 1h, 3h, 6h, 9h, and so on, for a period of 12 hours until it returns a 200, 201, or 202 success response. The notification event is marked as failed after this period.

To resend notifications after this period, please contact support or your technical account manager.