When an action occurs within the Dwolla system on a resource (External Parties, Transfers, etc.), an Event object is created to record a change to the state of the resource. All created Webhook Events follow the same format and include high level details such as: an event topic, a resource URL that identifies the specific resource that changed states, and a timestamp. If your application has an active webhook subscription, all Events relevant to your integration will trigger a webhook notification each time they occur. The following resource article will provide guidance on the structure of webhook events, which will assist with handling incoming webhooks.
Dwolla strongly encourages all applications to establish a webhook subscription in production. It’s a vital tool for receiving timely notifications about crucial actions within your Dwolla account, ensuring seamless updates and notifications for your end users.

​
Webhook request details

When your webhook subscription is configured, events will be created and sent asynchronously via webhooks as they occur. The webhook notification from Dwolla is a POST request that contains a JSON-encoded payload as well as HTTP headers, which are both used when consuming the webhook. Webhook payloads are designed to be lightweight with only minimum details regarding the triggered event. Dwolla returns links within the Event object pointing to relevant resources in the API which are used to lookup more detailed information on the resource that changed states.

​
Webhook headers

There are a few HTTP headers that are useful for your application when consuming the webhook request. X-Dwolla-Topic lets your app know, at a high level, the type of event being sent in the payload. X-Request-Signature-SHA-256 contains an HMAC SHA-256 hash based on the webhook payload and a key which is your webhook secret. The webhook signature should be processed and validated prior to parsing the webhook payload.
  • X-Dwolla-Topic - transfer:created
  • X-Request-Signature-SHA-256 - ed551cfb4acb48d31e14886bffa33aa417dfa4a3d3778f6141a7f7f92ee64861

​
Webhook payload

All webhook payloads will include an Event object. An Event contains _links to: the relevant resource that caused the Event to be triggered, the Account or External Party that the Event belongs to, and a self link to identify the unique Event. In addition to relevant _links, the payload will include attributes such as a created timestamp, event topic, and resourceId (see table below for more information).
AttributeDescription
_linksAn object that contains relevant links to resources in the Dwolla API. Possible links can include: self, account, resource, and external-party.
self - a link to the unique event
account - a link to the Dwolla account that the application belongs to
resource - a link to the resource that changed states. Used to lookup additional details returned on the resource itself
external-party - a link to the external-party the Event belongs to
idUnique Event ID. An Event ID is used along with the created timestamp for idempotent event processing.
createdISO-8601 timestamp of when the event was created.
topicType of action that occurred within Dwolla.
Format: <resource>.<related_resource>:<type/action> or <resource>:<type/action>.
For example, the event topic for when a transfer is created is transfer:created.
Other examples include: funding_source:removed, external_party:created.
resourceIdUnique ID of the resource that triggered the Event.

​
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": "transfer:created"
}

​
List of Webhook Events

The following list contains all supported events that can trigger a webhook notification to be sent using Dwolla Connect. New events may be added in the future, so be sure to check back on our changelog often. We also recommend subscribing to developer/product related updates to stay informed about the latest changes.

​
Funding Sources

Event Topic NameDescription
funding_source:createdDescription: A funding source was added to a main Dwolla Account.
Timing: Occurs upon a POST request to the Create a funding source for an account endpoint, or when a funding source is added via a third party bank verification method.
funding_source:removedDescription: A funding source was removed from a main Dwolla Account.
Timing: Occurs upon a POST request to the Remove a funding source endpoint.
external_party.funding_source:createdDescription: A funding source was added to an External Party.
Timing: Occurs upon a POST request to the Create a funding source for an external party endpoint, or when a funding source is added via a third party bank verification method.
external_party.funding_source:removedDescription: A funding source was removed from an External Partyt.
Timing: Occurs upon a POST request to the Remove a funding source endpoint.

​
External Parties

Event Topic NameDescription
external_party:createdDescription: An external party was created.
Timing: Occurs upon a POST request to the Create an external party endpoint.

​
Transfers

Event Topic NameDescription
transfer:createdDescription: An account-to-account transfer was created between a main Dwolla Account and an External Party.
Timing: Occurs upon a POST request to the Initiate a transfer endpoint when sending funds between a main Dwolla Account and an External Party.
transfer:pendingDescription: An account-to-account transfer was updated from created to pending. A pending status represents submission to a Financial Institution for processing.
Timing: Occurs immediately following the transfer:created event when a transaction is submitted for processing.
transfer:processedDescription: An account-to-account transfer was updated from pending to processed. A processed status represents completed processing with the Financial Institution.
Timing: Occurs when the transfer is expected to be successful based on the designated processing time.
transfer:failedDescription: An account-to-account transfer was updated from pending to failed.
Timing: Occurs after a transfer:pending event when a transaction fails processing after being submitted to the Financial Institution. Additional details are available in an embedded failureReason object when retrieving a transfer.
transfer:returnedDescription: An account-to-account transfer was updated to returned. A returned status represents an ACH debit/credit transfer that has been returned by the RDFI.
Timing: Occurs after a transfer has been submitted for processing by a Financial Institution following a transfer:pending or transfer:processed event when an ACH return has been issued by an RDFI. Additional details are available in an embedded failureReason object when retrieving a transfer.