Processing and Handling Webhooks

Webhooks are HTTP requests that are triggered by a Dwolla API event.

Dwolla uses webhooks to deliver useful information related to your application in near real time. For example, if the status of a transaction in your Dwolla Account changes from `pending` to `processed,` a webhook can notify your application of the status update without you having to explicitly look for it by polling the API. Webhooks are a more efficient and easier alternative to methods such as long polling.

In this blog post, I’ll walk through a project created by Dwolla called Webhook Receiver. The GitHub repository can be found using the link at the bottom of this blog. This project serves as a demo on how our webhooks are used. In the project, a webhook subscription is set up and a handler is created to handle any incoming events.

How Dwolla Uses Webhooks

Webhooks have quite a few moving parts. The following diagram provides a high level overview on how they work.

These are the steps to creating and handling a webhook subscription.

1. Make an API request to create a subscription to /webhook-subscriptions.
2. If the subscription is created successfully, Dwolla will trigger webhook requests for events related to your application.
3. When there is an event related to your application, Dwolla will send a webhook notifying you of that event to the supplied URL via a POST request.

Creating a Webhook Subscription

Creating a webhook subscription is as simple as making an API request to Dwolla’s /webhook-subscriptions endpoint. To create a subscription, a few things are required:

• Dwolla credentials for Sandbox or Production. This includes your application key and secret.
• A publicly-accessible URL from your application to send events to when they are generated.
• A randomly generated secret key related to your application. This is different from your Dwolla secret key.
• Set up AWS credentials since the example is deployed using AWS Lambda.

To begin, clone down the webhook receiver project and follow the instructions in the README to get the project running.

In the webhook receiver project, Dwolla’s Node SDK is used. Inside of scripts/client.ts a Dwolla client is created.

export const getClient = () =>
new Client({
environment: "sandbox",
key: process.env.DWOLLA_APP_KEY!,
secret: process.env.DWOLLA_APP_SECRET!
});

This should be created automatically once environment variables are set up correctly in the .env file.

Once that’s done, in the file scripts/one-time-setup.ts there is a function called runSetup. This function sets up the webhook subscription by making a request to /webhook-subscriptions. There is a variable called AWS_LAMBDA_URL at the top of the file; this needs to be set to the URL where Dwolla will send over events.

Processing Webhook Events

Now that you have a webhook subscription, Dwolla will send over webhook requests to the provided AWS Lambda URL. It is recommended that the handler for these requests pass these events onto a queue to be processed.

Inside of src/handlers/webhook.ts there’s a series of functions. One of them is isSignatureValid.

export const getClient = () =>const isSignatureValid = (body: string, signature: string): boolean =>
signature === crypto.createHmac("sha256", process.env.WEBHOOK_SECRET!).update(body).digest("hex");

This function checks to see if the request being made to your application is coming from Dwolla and is safe by using the secret key provided from your application. The event handler is doing some high level sanitizing and then sending the task over to a queue to be processed.

The queue can be found in src/handlers/queue.ts.

export const queueHandler: SQSHandler = async (event: SQSEvent): Promise => {
  try {
    event.Records.forEach((record: SQSRecord) => {
      const webhook: any = parseWebhook(record.body);
      console.log(`Received ${webhook.topic}, body=${JSON.stringify(webhook, null, 2)}`);
    });
  } catch (e) {
    console.error(`An error occurred while processing the queue: `, e);
  }
};

In the example above, the event is just printed to the console. This is where you would put your business logic.

Secure, Real-Time Communication

Webhooks are great to use for notification systems or any other use case where real-time communication is useful. They are also more robust and secure than long polling solutions. Also, they can be more convenient since you only need to manage one webhook URL vs. countless other API requests.

Now you’re ready to incorporate webhooks into your application. Dwolla’s documentation has a list of different webhook events, as well as some more instructions on using them.

Here are some useful links:
GitHub Repository
Webhook Subscriptions
List Events
Creating a Webhook Subscription