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 an External Party is created or a Funding Source is removed, a external_party:created and external_party.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.

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 External Party that the resource relates to (if applicable)

Example webhook payload:

{
  "_links": {
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/3b0f270c-9cfd-4724-bae8-aa4b1659cbb1"
    },
    "resource": {
      "href": "https://api-sandbox.dwolla.com/transfers/d75a1882-a051-4c92-9631-bfe0b252a24e"
    },
    "self": {
      "href": "https://api-sandbox.dwolla.com/events/021e2d1b-a71e-496e-8e5f-0c7bceac21c5"
    }
  },
  "created": "2023-09-27T15:44:30.152Z",
  "id": "021e2d1b-a71e-496e-8e5f-0c7bceac21c5",
  "resourceId": "d75a1882-a051-4c92-9631-bfe0b252a24e",
  "topic": "account.transfer:created"
}

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 via the 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.