Notifications

To maintain an informed state of your operations within the IO ecosystem, setting up a notification configuration is pivotal. This allows for real-time asynchronous updates pertaining to system events.

Delivery Methods

Choose the most suitable delivery method for your setup from the options provided:

Notification Delivery Methods	Availability
WEBHOOK	✅ Available
SLACK	❌ Planned
TELEGRAM	❌ Planned
EMAIL	❌ Planned

For immediate needs concerning delivery methods under development, please contact customer support.

Event Types

Stay updated with notifications across all event types accessible through the Events API.

Notification Configurations

Consult the Notification Configuration API for setting up your notifications.

Unique webhook targets are essential for each notification configuration; duplicating targets for different configurations will result in an error.

Webhooks

Construct a webhook notification-config to receive updates on key events such as FLOW_PAYOUT_PAID, FLOW_PAYIN_COMPLETED, and FLOW_PAYIN_RETURNED. Authorization is managed via an apiKey header.

Webhooks will be dispatched using the POST method.

{
    "target": "https://www.example.com/path",
    "events": ["FLOW_PAYOUT_PAID", "FLOW_PAYIN_COMPLETED", "FLOW_PAYIN_RETURNED"],
    "type": "WEBHOOK",
    "description": "Configuration for Payin and Payout Notifications",
    "config": {
        "params": {},
        "headers": {
            "apiKey": "yourSecretAPIKEY"
        }
    }
}

The outgoing request will resemble:

{
    "method": "POST",
    "url": "https://www.example.com/path",
    "headers": {
        "content-type": "application/json",
        "apiKey": "yourSecretAPIKEY"
    },
    "body": {
        "type": "FLOW_PAYIN_COMPLETED",
        "link": "https://api.iofinnet.com/v1/payins/515eb976-c423-48dd-9e0a-a825f52fecd7",
        "metadata": {
            "payin": {
                "id": "515eb976-c423-48dd-9e0a-a825f52fecd7"
            }
        }
    }
}

Requesting a Signed Webhook

For enhanced security, request a signature for your webhooks by setting "signRequest": true within your notification configuration.

{
    "target": "https://www.example.com/path",
    "events": ["FLOW_PAYOUT_PAID", "FLOW_PAYIN_COMPLETED", "FLOW_PAYIN_RETURNED"],
    "type": "WEBHOOK",
    "description": "Secure Payin and Payout Notification Configuration",
    "config": {
        "params": {},
        "headers": {
            "apiKey": "yourSecretAPIKEY"
        }
    },
    "signRequest": true
}

Verification of Signature

For signature verification, please request the public key from our customer support team.

Example of verifying a webhook signature in a JavaScript AWS Lambda function:

import fs from 'fs';
import crypto from 'crypto';

export const handler = async(event) => {
    const payload = event.body;
    const signature = event.headers['Signature'];

    const publicKeyPath = './publickey.pem';
    const publicKey = fs.readFileSync(publicKeyPath, 'utf8');

    let response;
    if (verifySignature(publicKey, payload, signature)) {
        response = {
            statusCode: 200,
            body: JSON.stringify({ message: 'Successfully verified payload.' })
        };
    } else {
        response = {
            statusCode: 400,
            body: JSON.stringify({ message: 'Failed to verify payload.' })
        };
    }
    
    console.log(response);
    return response;
};

function verifySignature(publicKey, payload, signature) {
    const verifier = crypto.createVerify('RSA-SHA256');
    verifier.update(payload);
    return verifier.verify(publicKey, signature, 'base64');
}