Webhook Events

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).

Attribute	Description
_links	An 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
id	Unique Event ID. An Event ID is used along with the created timestamp for idempotent event processing.
created	ISO-8601 timestamp of when the event was created.
topic	Type 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`.
resourceId	Unique 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 Name	Description
funding_source:created	Description: 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:removed	Description: 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:created	Description: 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:removed	Description: 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 Name	Description
external_party:created	Description: An external party was created. Timing: Occurs upon a POST request to the Create an external party endpoint.

Transfers

Event Topic Name	Description
transfer:created	Description: 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:pending	Description: 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:processed	Description: 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:failed	Description: 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:returned	Description: 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.

Introduction

Getting Started

Funds Flows

Customers

Funding Sources

Transfers

Integrations

Webhooks & Notifications

Webhook request details

Webhook headers

Webhook payload

Example webhook payload

List of Webhook Events

Funding Sources

External Parties

Transfers

​Webhook request details

​Webhook headers

​Webhook payload

​Example webhook payload

​List of Webhook Events

​Funding Sources

​External Parties

​Transfers

Webhook request details

Webhook headers

Webhook payload

Example webhook payload

List of Webhook Events

Funding Sources

External Parties

Transfers