Handling webhook deliveries

Introduction

When you setup a webhook, you specify a URL and subscribe to all event types. When an event occurs, Swipelux will send an HTTP request with data about the event to the URL that you specified. If your server is set up to listen for webhook deliveries at that URL, it can take action when it receives one.

This article describes how to write code to let your server listen for and respond to webhook deliveries. You will test your code by using your computer as a local server.

Setup

In order to test your webhook locally, you can use a webhook proxy URL to forward webhooks from Swipelux to your computer. This article uses smee.io to provide a webhook proxy URL and forward webhooks.

Get a webhook proxy URL

In your browser, navigate to https://smee.io/.
Click Start a new channel.
Copy the full URL under "Webhook Proxy URL". You will use this URL in the following setup steps.

Forward webhooks

If you don't already have smee-client installed, run the following command in your terminal:

npm install -g smee-client

To receive forwarded webhooks from smee.io, run the following command in your terminal. Replace WEBHOOK_PROXY_URL with your webhook proxy URL from earlier.

smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

You should see output that looks like this, where WEBHOOK_PROXY_URL is your webhook proxy URL:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL

Note that the path is /webhook and the port is 3000. You will use these values later when you write code to handle webhook deliveries.

Keep this running while you test out your webhook. When you want to stop forwarding webhooks, enter Ctrl+C in your terminal.

Set up a webhook URL

For the URL, use your WEBHOOK_PROXY_URL. For more information, see Configure webhooks.

Write webhook handler code

In order to handle webhook deliveries, you need to write code that will:

Initialize your server to listen for requests to your webhook URL
Read the HTTP headers and body from the request
Take the desired action in response to the request

You can use any programming language that you can run on your server. This article uses Node.js and Express to handle webhook deliveries.

This example requires your computer or codespace to run Node.js version 12 or greater and npm version 6.12.0 or greater. For more information, read this article.

Create a new Node.js project

Create a new directory for your project and initialize it:

mkdir webhook-handler
cd webhook-handler
npm init -y

Install the required dependencies:

npm install express body-parser

Create the server file

Create a new file called server.js and add the following code:

const express = require('express');
 
const app = express();
 
app.post('/webhook', express.json({ type: 'application/json' }), (req, res) => {
  // Log the webhook payload
  console.log('Received webhook:', req.body);
 
  // Send a response to acknowledge receipt
  res.status(200).send('Webhook received');
});
 
// Start the server
const PORT = 3000;
 
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

Start the server

Run your server using Node.js:

node server.js

You should see the message: Server is running on port 3000

Your webhook endpoint is now ready to receive requests at http://localhost:3000/webhook.

Test the webhook

To test your webhook, you can use your computer to act as a local server. If you have trouble with these steps, see Troubleshooting.

Make sure that you are forwarding webhooks. If you are no longer forwarding webhooks, follow the steps in Forward webhooks again.

Make sure that your server is running. If it is not running, follow the steps in Start the server again.

Trigger your webhook. For example, by creating a new transfer for your test customer.

Check your server logs to see the webhook payload.

Next steps

This article demonstrated how to write code to handle webhook deliveries. It also demonstrated how to test your code by using your computer as a local server and by forwarding webhook deliveries from Swipelux to your local server via smee.io. Once you are done testing your code, you might want to modify the code and deploy your code to a server.

Verify that the delivery is from Swipelux

In your code that handles webhook deliveries, you should validate that the delivery is from Swipelux before processing the delivery further. For more information, see Validate webhook deliveries.

Deploy your code to a server

This article demonstrated how to use your computer or codespace as a server while you develop your code. Once the code is ready for production use, you should deploy your code to a dedicated server.

When you do so, you may need to update your code to reflect the host and port where your server is listening.

Update the webhook URL

Once you have a server that is set up to receive webhook traffic from Swipelux, update the URL in your webhook settings. You may need to update the route that your code handles to match the path portion of the new URL. For example, if your new webhook URL is https://example.com/swipelux-webhooks, you should change the route in these examples from /webhook to /swipelux-webhooks.

You should not use smee.io to forward your webhooks in production.

On this page