Handling webhook deliveries

Learn how to write code to listen for and respond to webhook deliveries.

Introduction

When you create a webhook, you specify a payload URL and subscribe to event types. When an event that your webhook is subscribed to occurs, Shopwaive 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 can test your code by using your computer or codespace as a local server.

Step-by-step:

Create a webhook with the following settings. For more information, see "Creating webhooks."

• For the payload URL, create an endpoint defined on your server that you'll receive the webhook request

Write code to handle webhook deliveries

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

• Initialize your server to listen for requests to your webhook payload 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. The following example prints a message when a webhook delivery is received. However, you can modify the code to take another action, such as making a request to the Shopwaive REST API or sending an email

JavaScript example

Create a JavaScript file with the following contents. Modify the code to handle the event types that your webhook is subscribed to, as well as the ping event that Shopwaive sends when you create a webhook. This example handles the available_balance and ping events.

const express = require('express');

// This initializes a new Express application.
const app = express();

// Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
app.post('/PATH_TO_PAYLOAD_ENDPOINT', express.json({type: 'application/json'}), (request, response) => {

  // Respond to indicate that the delivery was successfully received.
  // Your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then Shopwaive terminates the connection and considers the delivery a failure.
  response.status(202).send('Accepted');

  // Check the `x-shopwaive-event` header to learn what event type was sent.
  const shopwaiveEvent = request.headers['x-shopwaive-event'];

  // You should add logic to handle each event type that your webhook is subscribed to.
  // For example, this code handles the `available_balance` and `ping` events.
  // If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  // For example, this code handles the `redeemed` and `adjusted` actions for the     `available_balance` event.
  //
  if (shopwaiveEvent === 'available_balance') {
    const data = request.body;
    const action = data.action;
    if (action === 'redeemed') {
      console.log(`An available_balance was redeemed with this transactional amount: ${data.available_balance.transaction}`);
    } else if (action === 'adjusted') {
      console.log(`An available_balance was adjusted by this transactional amount ${data.available_balance.transaction}`);
    } else {
      console.log(`Unhandled action for the issue event: ${action}`);
    }
  } else if (shopwaiveEvent === 'ping') {
    console.log('Shopwaive sent the ping event');
  } else {
    console.log(`Unhandled event: ${shopwaiveEvent}`);
  }
});

// This defines the port where your server should listen.
// 3000 matches the port that you specified for webhook forwarding. 
// Once you deploy your code to a server, you should change this to match the port where your server is listening.
const port = 3000;

// This starts the server and tells it to listen at the specified port.
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

Test the code

1. Trigger your webhook. For example, if you created an organization webhook that is subscribed to the available_balance event, change an available balance of a customer in your organization.

2. Navigate to your webhook payload URL on your server console. You should see an event that corresponds to the event that you triggered. This indicates that Shopwaive successfully sent a webhook delivery to the payload URL that you specified.