How to Set Up Webhooks

Setting up webhooks for i-payout involves the following steps:

Step 1: Authenticate: Obtain an API token by validating your credentials.

Step 2: Create Webhook: Register a new webhook to receive notifications.

Step 3: Activate Webhook: Activate the webhook subscription.

Step 4: Verify Webhook Signatures: Ensure the authenticity and integrity of webhook notifications.

API Endpoints Used

In this guide, you will use the following API endpoints:

Below, you will go through the necessary API calls to achieve the steps above within the i-payout system.

📘

Recipe

You can also follow our recipe by clicking the link below:

🦉

How to Set Up Webhooks

Open Recipe

Step 1: Authenticate

To start using i-payout solutions, you will need to authenticate with your API Token. Refer to the Get a Token guide to learn how to:

Step 2: Create Webhook

To receive real-time notifications about various events, you need to set up webhooks. Use the Create Webhook endpoint to create a webhook subscription. Below, you will find an example request to create a webhook:

curl --request POST \
     --url "https://merchantapi.testewallet.com/api/v1/webhooks" \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '{
         "event": "PAYMENT.COMPLETED",
         "url": "https://yourwebhookurl.com/notification",
         "description": "Webhook for payment completion"
     }'

{
  "isSuccess": true,
  "message": "Webhook created successfully",
  "statusCode": 200,
  "logIdentifier": "xyz789hij012",
  "data": {
    "webhookToken": "webhooktoken123",
    "event": "PAYMENT.COMPLETED",
    "url": "https://yourwebhookurl.com/notification",
    "status": "active"
  }
}

Step 3: Activate Webhook

After creating the webhook, you need to activate the subscription. Use the Activate Webhook endpoint. Below, you will find an example request to activate a webhook:

curl --request POST \
     --url "https://merchantapi.testewallet.com/api/v1/webhooks/<token>/activate" \
     --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
     --header 'X-MerchantId: <YOUR_MERCHANT_ID>' \
     --header 'accept: application/json'

{
  "isSuccess": true,
  "message": "Webhook activated successfully",
  "statusCode": 200,
  "logIdentifier": "ijk456lmn789",
  "data": {
    "webhookToken": "webhooktoken123",
    "status": "active"
  }
}

Step 4: Verify Webhook Signatures

Webhook security for i-payout involves using digital signatures to ensure the authenticity and integrity of the webhook notifications. This process involves signing the webhook payload with a private key and verifying the signature using a public key.

Key Components

Headers

• x-timestamp: This is the current Unix timestamp (number of seconds since epoch) when the webhook notification is sent. It ensures the request's freshness and helps prevent replay attacks.
• x-signature: This is the message's signature, created using the private RSA key and the SHA256 hash of the SignatureBody. It is Base64 encoded.

SignatureBody

The format of the SignatureBody is:

timestamp + "#" + NotificationUrl + "#" + JsonBody

• timestamp: The Unix timestamp.
• NotificationUrl: The URL to which the notification is sent.
• JsonBody: The JSON payload of the webhook notification.

Signature Generation

The SignatureBody is signed using the private RSA key and SHA256 hash algorithm to create the signature. The signature is then Base64 encoded and included in the x-signature header.

Signature Verification

The client (receiver of the webhook) needs to use the public RSA key to verify the signature. The client constructs the SignatureBody in the same format, computes the SHA256 hash, and verifies it against the decoded signature using the public key.

Public Keys

i-payout utilizes the POST HTTP method and JSON payloads to send requests to your webhook URL.

By following this security model, you can ensure that the webhook notifications you receive are authentic and tamper-proof. This provides a secure method for keeping your system updated with real-time events.