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.
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.
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:createdX-Request-Signature-SHA-256
- ed551cfb4acb48d31e14886bffa33aa417dfa4a3d3778f6141a7f7f92ee64861All 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. |
{
"_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"
}
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.
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. |
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. |
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. |
All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.