Working with Dwolla Webhooks #

A webhook is a means of notifying your application of the occurrence of an event with some relevant information. Events are created each time a resource is created or updated in Dwolla. For example, when a Customer is created or a Funding Source is removed, a customer_created and customer_funding_source_removed event will be created, respectively. These events are what trigger HTTP webhook requests to your subscribed URL if you have an active webhook subscription. It is important to note that a single API request can trigger multiple webhooks to be fired, e.g. initiating a transfer from an Account to Customer can create the events transfer_created and customer_transfer_created.

Check out our API reference for an exhaustive list of all possible events.

Webhook Event #

Each webhook contains an Event with _links to the following resources:

• The unique event itself
• The Dwolla Account associated with the event
• The Resource associated with the event
• The Customer that the resource relates to (if applicable)

Example webhook payload:

{
  "id": "80d8ff7d-7e5a-4975-ade8-9e97306d6c15",
  "resourceId": "36E9DCB2-889B-4873-8E52-0C9404EA002A",
  "topic": "customer_created",
  "timestamp": "2015-10-22T14:44:11.407Z",
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/events/80d8ff7d-7e5a-4975-ade8-9e97306d6c15"
    },
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/b4cdac07-eeca-4059-a29c-48900e453d54"
    },
    "resource": {
      "href": "https://api-sandbox.dwolla.com/customers/36E9DCB2-889B-4873-8E52-0C9404EA002A"
    },
    "customer": {
      "href": "https://api-sandbox.dwolla.com/customers/36E9DCB2-889B-4873-8E52-0C9404EA002A"
    }
  }
}

For detailed information on Dwolla's webhook request structure, refer to the Webhook Events resource.

What to Know About Dwolla Webhooks #

• Each application can have multiple webhook subscriptions associated with it. While one subscription is sufficient, you can create up to five in Production and ten in Sandbox for redundancy.
• Webhooks are sent asynchronously and are not guaranteed to be delivered in order. We recommend that applications protect against duplicated events by making event processing idempotent.
• Your application will need to respond to Dwolla webhook requests with a 200-level HTTP status code within 10 seconds of receipt. Otherwise, the attempt will be counted as a failure and Dwolla will retry sending the webhook according to the back-off schedule.
• If there are 400 consecutive failures, and it has been 24 hours since your last success, your webhook subscription will be automatically paused and an email will be sent to the Admin of the Dwolla account. After fixing the issue that is causing the failures, you can unpause the webhook subscription either via your Dashboard or Dwolla's API in order to continue receiving new webhooks and to retry failed webhooks.

Getting Started #

In this guide we will walk through creating a webhook subscription along with validating and processing webhook requests.

You will need to have a Sandbox account already set up. Although not required, this guide assumes that you have some familiarity with Amazon Web Services (AWS); specifically Lambda and SQS, or other similar services.