API / Webhooks

Notification hooks

Dwolla API consumer applications can subscribe to Webhook Notifications. These Notifications are messages pushed to a subscribed URL as specified by the application owner. Notifications act as a private messaging system giving the application owner messages related to events triggered or initiated by their application's usage of the Dwolla API. Use Notifications to track the progress of transactions tied to your consumer application without polling for information.

Available Notifications

Click on any of the available types to see a detailed explanation of the notification:

  • Transaction Status - receive webhook notifications when the status of a transaction that is associated with your application changes.
  • Transaction Returned - receive webhook notifications when a bank funded transaction fails.
  • Request Fulfilled - receive webhook notifications when requests that were made using your application are fulfilled.
  • Request Cancelled - receive webhook notifications when pending requests that were made using your application are cancelled by either parties.

Webhook Signatures

Every Webhook notification originating from Dwolla will be accompanied by a signature, so that you can validate the origin of the message. The signature will be posted in the X-Dwolla-Signature header, and is an HMAC hash of the request body salted using the consumer application secret.

Here's an example of validating a webhook signature using NodeJS:

function validate_webhook_signature(body, secret, signature) {
  var crypto = require('crypto');

  hash = crypto
    .createHmac('sha1', secret)

  return (hash == signature);

How Notifications Work

1. Dwolla sends a HTTP POST request

When you enable Notifications, Dwolla servers will automatically attempt to POST a request with a JSON body to the Notification Url(s) specified. The JSON contains standard properties defining the notification type and other information relevant to the notification type.

Although Notifications are asynchronous, the information sent with the request will always follow the corresponding information on Dwolla.com and, where exposed, the information available via the Dwolla API. For example, if you subscribe an application to transaction status Notifications, the status value sent via the Notification contains the same status you'd see on Dwolla.com or in a response from Dwolla's transactions API for the given transaction.

2. Consumer application sends a HTTP response

Your server needs to be set up to receive the request from Dwolla at the publicly visible Notification URL(s) you've subscribed and needs to respond with an HTTP status code of OK (200), otherwise Dwolla assumes a temporary problem and immediately retries the POST request two times in succession.

Setup Notifications

Notifications are setup per application through the application's feature page by entering the URL(s) you'd like Dwolla to notify.