Skip to main content

Webhooks

A webhook request will be triggered whenever a payment is either paid or canceled. This request serves as a notification to inform your server about the change in the payment status. By configuring your webhook endpoint, you can automatically receive updates and take appropriate actions based on whether the payment was paid or canceled.

What is a webhook?

A webhook is an automated message sent from one server to another when an event occurs. It enables real-time data transfer between systems.

Requirements​

In order to receive a webhook notification, you will need:

  • A fetchable URL endpoint. You can set it here.
  • Your Webhook Token: abcd... which can be found in your dashboard here.
warning

It's crucial to keep your Webhook Token confidential.

The HTTPS Notification​

A POST request will be sent from our server to your endpoint with a JSON payload similar to:

{
  "token": "abcd...", // Your Webhook Token
  "paymentID": "0123456789",
  "payment_status": "1" // The payment is completed.
}

Security Note: To ensure the integrity and authenticity of the payload data, it is strongly recommended to verify that the token in the payload matches the Webhook Token displayed on your dashbaord.

note

Please see here all possible payment_status codes

Webhook Response Expectations​

Your server must respond with a JSON payload using a POST request, confirming the successful reception of the webhook, as shown below:

{
  "status": "received"
}
danger

If your server does not return this response, the webhook will be considered failed, and a new request will be retried at different time intervals (see here).

Webhook Code Example​

The following code snippets are functional examples of webhooks and can be directly integrated into your backend. You are free to edit and modify them as needed to suit your specific requirements. These examples are provided to assist you in seamlessly integrating our webhooks into your system.

Click to expand JS code
// webhook.js file
/*
=============================================================================================
This script handles incoming payment notifications from SwayCoin.io via webhooks.

It processes the `paymentID` and `payment_status` sent in the request, and verifies the authenticity 
of the notification using the `token` included in the webhook. 

The script performs the following steps:
1. Validates the webhook request by checking the token, paymentID format and payment_status format.
2. Executes actions based on the payment status (paid or canceled).
3. Responds with a JSON confirmation once the payment notification is processed.

Ensure the following:
- The token must match the Webhook Token from your dashboard.
- The payment status should be either 1 (paid) or 0 (canceled by the user).

For more information on webhook integration, refer to the official documentation:
https://docs.swaycoin.io/

Feel free to modify this script to suit your specific needs.
=============================================================================================
*/

const WEBHOOK_TOKEN = 'YOUR_WEBHOOK_TOKEN';
const ALLOW_TEST_PAYMENT = true; // Enable test mode to allow alphanumeric paymentIDs

const express = require('express');
const app = express();
app.use(express.json()); // Middleware to parse JSON input

app.post('/webhook', (req, res) => {
   const { token, paymentID, payment_status, message } = req.body;

   // Webhook Endpoint Testing. THIS CODE CAN BE SAFELY DELETED
   if (isTestNotification(token, message)) {
      return res.json({ message: 'Webhook Notification Received' });
   }

   // Validate the webhook request
   if (isValidRequest(token, paymentID, payment_status)) {

      if (payment_status == 1) {
         // Handle paid payment
      } else if (payment_status == 0) {
         // Handle canceled payment
      }

      return res.json({ status: 'received' });
   } else {
      // This flags the webhook as failed, prompting SwayCoin.io to retry automatically.
      // For more details on retry mechanisms, refer to the documentation: 
      // https://docs.swaycoin.io/others/webhook#automatic-retrys
      return res.status(400).json({ status: 'Custom Error' });
   }

});

// Check the validity of the request
function isValidRequest(token, paymentID, payment_status) {
   // Check if the provided token matches the expected one
   if (token != WEBHOOK_TOKEN) {
      return false; // Invalid token
   }

   // Validate the paymentID format (should be a 10-digit numeric string)
   if (!isValidPaymentIDFormat(paymentID)) {
      return false; // Invalid paymentID format
   }

   // Check if the payment status is valid (either 1 for paid or 0 for canceled)
   if (![0, 1].includes(payment_status)) {
      return false; // Invalid payment status
   }

   return true; // All conditions are met
}

function isValidPaymentIDFormat(paymentID) {
   // For test paymentID: Allow 10-letter string as valid paymentID format too
   if (ALLOW_TEST_PAYMENT) {
      return paymentID.length === 10 && /^[a-zA-Z0-9]+$/.test(paymentID);
   }
   return /^\d{10}$/.test(paymentID);
}

// Check the validify of the test notification webhook. THIS CODE CAN BE SAFELY DELETED
function isTestNotification(token, message) {
   // Check if the provided token matches the expected one
   if (token != WEBHOOK_TOKEN) {
      return false; // Invalid token
   }

   if (!message) {
      return false; // No Test Message
   }

   return true; // All conditions are met
}

const port = 3000;
app.listen(port, () => {
   console.log(`Server running on port ${port}`);
});

Testing the Webhook​

The provided example code includes a dedicated section for testing. To test your webhook, use the Test Webhook button available in your dashboard.

This feature sends a predefined test payload to your webhook, which should return the following default message:

Webhook Notification Received

If the webhook does not respond correctly, potential issues could include:

  • Firewall or CORS policy restrictions.
  • The test code may have been removed from your implementation.

Automatic Retrys​

If a webhook fails, it will be automatically retried up to 5 times with increasing delays between each attempt:

  • 1st Retry: after 5 Min
  • 2nd Retry: after 15 Min
  • 3rd Retry: after 1 Hour
  • 4th Retry: after 5 Hour
  • 5th Retry: after 24 Hour
note

If you prefer not to receive webhook retries after a failure, you can disable this feature in your dashboard settings.

Possible payment_status codes​

payment_statusStatusDescription
1PaidThe user has sent the required amount, and the transaction has been confirmed by the blockchain.
0FailedThe payment has been canceled by the user.