> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Real-time event notifications. Determine why a webhook subscription is vital to the experience of your application.

## Overview

When an action occurs within the Dwolla system on a resource (Customers, 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](/docs/working-with-webhooks), 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.

<Info>
  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.
</Info>

## 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](/docs/working-with-webhooks#step-2-processing-and-validating-webhooks) prior to parsing the webhook payload.

* `X-Dwolla-Topic` - customer\_created
* `X-Request-Signature-SHA-256` - ed551cfb4acb48d31e14886bffa33aa417dfa4a3d3778f6141a7f7f92ee64861

## Webhook payload

All webhook payloads will include an Event object which will follow the same format as outlined in the [API reference docs](/docs/api-reference/events). An Event contains `_links` to: the relevant resource that caused the Event to be triggered, the Customer 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`, `resourceId`, and conditionally a `correlationId` (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 `customer`. <br /> `self` - a link to the unique event <br /> `account` - a link to the Dwolla account that the application belongs to <br /> `resource` - a link to the resource that changed states. Used to lookup additional details returned on the resource itself <br /> `customer` - a link to the customer 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 when event was created.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| topic         | Type of action that occurred with Dwolla.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| resourceId    | Unique ID of the resource that triggered the Event.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| correlationId | Unique ID that was specified, if any, when a [transfer was created](/docs/api-reference/transfers/initiate-a-transfer).<br />**This value is only present for [transfer and transfer-related webhooks](#customers---transfers).**                                                                                                                                                                                                                                              |

### Example webhook payload

```json theme={"dark"}
{
  "_links": {
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/0ee84069-47c5-455c-b425-633523291dc3",
      "resource-type": "account",
      "type": "application/vnd.dwolla.v1.hal+json"
    },
    "customer": {
      "href": "https://api-sandbox.dwolla.com/customers/a6f09251-c2de-4833-94a8-5c70916cebbc",
      "resource-type": "customer",
      "type": "application/vnd.dwolla.v1.hal+json"
    },
    "resource": {
      "href": "https://api-sandbox.dwolla.com/customers/a6f09251-c2de-4833-94a8-5c70916cebbc",
      "type": "application/vnd.dwolla.v1.hal+json"
    },
    "self": {
      "href": "https://api-sandbox.dwolla.com/events/29a82d20-a703-41cb-9b3c-bd409c499925",
      "resource-type": "event",
      "type": "application/vnd.dwolla.v1.hal+json"
    }
  },
  "created": "2019-05-30T18:21:11.490Z",
  "id": "29a82d20-a703-41cb-9b3c-bd409c499925",
  "resourceId": "a6f09251-c2de-4833-94a8-5c70916cebbc",
  "topic": "customer_created"
}
```

## List of Customer related events by resource

Customer related webhooks are available for the list of Events shown below. As API enhancements are made, Dwolla may add new Events at any point in the future. A complete list of supported Events can be found in the [API docs](/docs/api-reference/events/list-events).

<Info>
  The Event topic for all events triggered for your end users that are created
  as Customers will be prepended with <code>customer\_\*</code>. Events that
  represent actions being triggered on your primary Dwolla Account are not shown
  below. Refer to the <a href="/docs/api-reference/events/list-events">API docs</a> for
  the complete list of Events.
</Info>

### Customers

<ResponseField name="customer_created" type="event">
  A Customer was created.

  **Timing:** Occurs upon a POST request to the [Create a Customer](/docs/api-reference/customers/create-a-customer) endpoint.
</ResponseField>

<ResponseField name="customer_kba_verification_needed" type="event">
  The retry identity verification attempt failed due insufficient scores on the submitted data. The end user will have a single KBA attempt to answer a set of "out of wallet" questions about themselves for identity verification.

  **Timing:** Occurs after a failed attempt to verify a Verified Customer Record.
</ResponseField>

<ResponseField name="customer_kba_verification_failed" type="event">
  The end user failed KBA verification and was unable to correctly answer at least three KBA questions.

  **Timing:** Triggered after a single attempt at verifying a Verified Customer Record using KBA.
</ResponseField>

<ResponseField name="customer_kba_verification_passed" type="event">
  The end user was able to correctly answer at least three KBA questions.

  **Timing:** Triggered after a Verified Customer Record successfully passes KBA requirements.
</ResponseField>

<ResponseField name="customer_reverification_needed" type="event">
  Incomplete information was received for a Customer; updated information is needed to verify the Customer.

  **Timing:** Occurs upon a POST request to the [Update a Customer](/docs/api-reference/customers/update-a-customer) endpoint, or when Dwolla places a Customer into retry status.
</ResponseField>

<ResponseField name="customer_verification_document_needed" type="event">
  Additional documentation is needed to verify a Customer.

  **Timing:** Occurs when a second attempt to re-verify a Customer fails, which systematically places the Customer in document status immediately after a POST request to the [Update a Customer](/docs/api-reference/customers/update-a-customer) endpoint.
</ResponseField>

<ResponseField name="customer_verification_document_uploaded" type="event">
  A verification document was uploaded for a Customer.

  **Timing:** Occurs upon a POST request to the [Create a Document](/docs/api-reference/documents/create-a-document-for-a-customer) endpoint.
</ResponseField>

<ResponseField name="customer_verification_document_failed" type="event">
  A verification document was rejected for a Customer.

  **Timing:** Occurs when a document uploaded for a Customer is reviewed by Dwolla, and rejected with a document failure reason, usually within 1-2 business days of uploading a document.
</ResponseField>

<ResponseField name="customer_verification_document_approved" type="event">
  A verification document was approved for a Customer.

  **Timing:** Occurs when a document uploaded for a Customer is reviewed by Dwolla, and approved, usually within 1-2 business days of uploading a document.
</ResponseField>

<ResponseField name="customer_verified" type="event">
  A Customer was verified.

  **Timing:** Occurs when a Customer is verified by Dwolla upon a POST request to the [Create a Customer](/docs/api-reference/customers/create-a-customer) endpoint. In a case where the Customer isn't instantly verified upon creation, this event occurs when the Customer is verified after a `retry` attempt, or after a document is approved.
</ResponseField>

<ResponseField name="customer_suspended" type="event">
  A Customer was suspended.

  **Timing:** Occurs when Dwolla systematically places a Customer in `suspended` status as a result of uploading fraudulent document, or upon receiving certain ACH return codes when a transfer fails.
</ResponseField>

<ResponseField name="customer_activated" type="event">
  A Customer moves from deactivated or suspended to an active status.

  **Timing:** Occurs upon reactivating a Customer that has a `deactivated` status by making a POST request to the [Update a Customer](/docs/api-reference/customers/update-a-customer) endpoint, or when Dwolla reactivates a Customer that has a `suspended` status.
</ResponseField>

<ResponseField name="customer_deactivated" type="event">
  A Customer was deactivated.

  **Timing:** Occurs upon deactivation of a Customer by making a POST request to the [Update a Customer](/docs/api-reference/customers/update-a-customer) endpoint, or when Dwolla systematically deactivates a Customer upon receiving certain ACH return codes when a transfer fails.
</ResponseField>

### Customers - Beneficial Owners

<ResponseField name="customer_beneficial_owner_created" type="event">
  A Beneficial owner was successfully created.

  **Timing:** Occurs upon a POST request to the [Create a beneficial owner](/docs/api-reference/beneficial-owners/create-beneficial-owner) endpoint.
</ResponseField>

<ResponseField name="customer_beneficial_owner_removed" type="event">
  An individual beneficial owner has been successfully removed from the Customer.

  **Timing:** Occurs upon a POST request to the [Remove a beneficial owner](/docs/api-reference/beneficial-owners/delete-beneficial-owner) endpoint.
</ResponseField>

<ResponseField name="customer_beneficial_owner_verification_document_needed" type="event">
  Additional documentation is needed to verify an individual beneficial owner.

  **Timing:** Occurs when a second attempt to re-verify a beneficial owner fails, which systematically places the beneficial owner in document status immediately after a POST request to the [Update a beneficial owner](/docs/api-reference/beneficial-owners/update-beneficial-owner) endpoint.
</ResponseField>

<ResponseField name="customer_beneficial_owner_verification_document_uploaded" type="event">
  A verification document was uploaded for beneficial owner.

  **Timing:** Occurs upon a POST request to the [Create a document for a beneficial owner](/docs/api-reference/documents/create-a-document-for-beneficial-owner) endpoint.
</ResponseField>

<ResponseField name="customer_beneficial_owner_verification_document_failed" type="event">
  A verification document was rejected for a beneficial owner.

  **Timing:** Occurs when a document uploaded for a beneficial owner is reviewed by Dwolla, and rejected with a document failure reason, usually within 1-2 business of uploading a document.
</ResponseField>

<ResponseField name="customer_beneficial_owner_verification_document_approved" type="event">
  A verification document was approved for a beneficial owner.

  **Timing:** Occurs when a document uploaded for a Customer is reviewed by Dwolla, and approved, usually within 1-2 business days of uploading a document.
</ResponseField>

<ResponseField name="customer_beneficial_owner_reverification_needed" type="event">
  A previously verified beneficial owner status has changed due to either a change in the beneficial owner's information or at request for more information from Dwolla. The individual will need to verify their identity within 30 days.

  **Timing:** Occurs upon a POST request to the [Update a beneficial owner](/docs/api-reference/beneficial-owners/update-beneficial-owner) endpoint, or when Dwolla places the beneficial owner into incomplete status.
</ResponseField>

<ResponseField name="customer_beneficial_owner_verified" type="event">
  A beneficial owner has been verified.

  **Timing:** Occurs when a Beneficial Owner is verified by Dwolla upon a POST request to the [Create a beneficial owner](/docs/api-reference/beneficial-owners/create-beneficial-owner) endpoint. In a case where the Beneficial Owner isn't instantly verified upon creation, this event occurs when the Beneficial Owner is verified after an update, or after a document is approved.
</ResponseField>

### Customers - Exchanges

<ResponseField name="customer_exchange_reauth_required" type="event">
  An exchange has been deactivated (or is pending deactivation) and requires reauthentication.

  **Timing:** Occurs when access to a user's connected bank account has been interrupted. This interruption could be due to changes on the bank's end, such as a password update, multi-factor authentication reset or revoked consent. This event signals that a user's bank connection needs to be refreshed by [creating a reauth exchange session](/docs/api-reference/exchange-sessions/create-re-authentication-exchange-session).
</ResponseField>

### Customers - Funding Sources

<ResponseField name="customer_funding_source_added" type="event">
  A funding source was added to a Customer.

  **Timing:** Occurs upon a POST request to the [Create a funding source for a customer](/docs/api-reference/funding-sources/create-customer-funding-source) endpoint, or when a funding source is added via drop-in components or a third party bank verification method.
</ResponseField>

<ResponseField name="customer_funding_source_removed" type="event">
  A funding source was removed from a Customer.

  **Timing:** Occurs upon a POST request to the [Remove a funding source](/docs/api-reference/funding-sources/update-or-remove-a-funding-source) endpoint, or when Dwolla systematically removes a funding source upon receiving certain ACH return codes when a transfer fails.
</ResponseField>

<ResponseField name="customer_funding_source_verified" type="event">
  A Customer's funding source was marked as verified.

  **Timing:** Occurs upon a POST request to the [Verify micro-deposits](/docs/api-reference/funding-sources/initiate-or-verify-micro-deposits) endpoint with the correct amounts, or when a funding source is added + verified via a third-party bank verification method. Also occurs in cases where Dwolla manually marks a funding source as verified.
</ResponseField>

<ResponseField name="customer_funding_source_unverified" type="event">
  A funding source has been systematically unverified. This is generally a result of a transfer failure.

  **Timing:** Occurs when Dwolla systematically marks a funding source unverified upon receiving certain ACH return codes when a transfer fails.
</ResponseField>

<ResponseField name="customer_funding_source_negative" type="event">
  A Customer's balance has gone negative. You are responsible for ensuring a zero or positive Dwolla balance for Customer accounts created by your application. If a Customer's Dwolla balance has gone negative, you are responsible for making the Dwolla Customer account whole. Dwolla will notify you via a webhook and separate email of the negative balance.

  **Timing:** Occurs upon a POST request to the [Initiate a transfer](/docs/api-reference/transfers/initiate-a-transfer) endpoint that causes a funding source balance to go negative.
</ResponseField>

<ResponseField name="customer_funding_source_updated" type="event">
  A Customer's funding source has been updated. This can also be fired as a result of a correction after a bank transfer processes.

  **Timing:** Occurs upon a POST request to the [Update a funding source](/docs/api-reference/funding-sources/update-or-remove-a-funding-source) endpoint. For example, a financial institution can issue a correction to change the bank account type from checking to savings.
</ResponseField>

<ResponseField name="customer_microdeposits_added" type="event">
  Two less than or equal to ten cent transfers to a Customer's linked bank account were initiated.

  **Timing:** Occurs upon a POST request to the [Initiate micro-deposits](/docs/api-reference/funding-sources/initiate-or-verify-micro-deposits) endpoint.
</ResponseField>

<ResponseField name="customer_microdeposits_failed" type="event">
  The two less than or equal to ten cent transfers to a Customer's linked bank account failed to clear successfully.

  **Timing:** Occurs when micro-deposits fail to clear into a bank account, usually within 1-2 business days of initiating them.
</ResponseField>

<ResponseField name="customer_microdeposits_completed" type="event">
  The two less than or equal to ten cent transfers to a Customer's linked bank account were successful.

  **Timing:** Occurs when micro-deposits are successful, usually within 1-2 business days of initiating them.
</ResponseField>

<ResponseField name="customer_microdeposits_maxattempts" type="event">
  The Customer has reached their max verification attempts, limit of three. The Customer can no longer verify their funding source with the completed micro-deposit amounts.

  **Timing:** Occurs upon the third POST request to the [Verify micro-deposits](/docs/api-reference/funding-sources/initiate-or-verify-micro-deposits) endpoint with incorrect micro-deposit amounts.
</ResponseField>

### Customers - Transfers

For transfer webhooks, in addition to the [default payload keys](#webhook-payload), a `correlationId` key-value pair *may* be present if a value was specified when the [transfer was created](/docs/api-reference/transfers/initiate-a-transfer).

<ResponseField name="customer_bank_transfer_created" type="event">
  A bank transfer was created for a Customer. Represents funds moving either from a verified Customer's bank to the Dwolla Platform or from the Dwolla Platform to a verified Customer's bank.

  **Timing:** Occurs upon a POST request to the [Initiate a transfer](/docs/api-reference/transfers/initiate-a-transfer) endpoint when sending funds from a Verified Customer's bank, or when funds move from a receiving Verified Customer's balance to their bank.
</ResponseField>

<ResponseField name="customer_bank_transfer_cancelled" type="event">
  A pending Customer bank transfer has been cancelled, and will not process further. Represents a cancellation of funds either transferring from a verified Customer's bank to the Dwolla Platform or from the Dwolla Platform to a verified Customer's bank.

  **Timing:** Occurs upon a POST request to the [Cancel a transfer](/docs/api-reference/transfers/cancel-a-transfer) endpoint, or when Dwolla manually cancels a transfer.
</ResponseField>

<ResponseField name="customer_bank_transfer_failed" type="event">
  A Customer bank transfer failed. Usually, this is a result of an ACH failure (insufficient funds, etc.). Represents a failed funds transfer either from a verified Customer's bank to the Dwolla Platform or from the Dwolla Platform to a verified Customer's bank.

  **Timing:** Occurs when Dwolla marks a transfer as failed.
</ResponseField>

<ResponseField name="customer_bank_transfer_creation_failed" type="event">
  Transfers initiated to a verified Customer's bank must pass through the verified Customer's balance before being sent to a receiving bank. Dwolla will fail to create a transaction intended for a verified Customer's bank if the funds available in the balance are less than the transfer amount.

  **Timing:** Occurs when a transfer to a verified Customer's bank fails to be created.
</ResponseField>

<ResponseField name="customer_bank_transfer_completed" type="event">
  A bank transfer that was created for a Customer was successful. Represents a successful funds transfer either from a verified Customer's bank to the Dwolla Platform or from the Dwolla Platform to a verified Customer's bank.

  **Timing:** Occurs when a funds transfer into the Dwolla Platform or a verified Customer's bank is successful, based on the transfer processing timing used.
</ResponseField>

<ResponseField name="customer_transfer_created" type="event">
  A transfer was created for a Customer. Represents funds transferring from a verified Customer's balance or unverified Customer's bank.

  **Timing:** Occurs upon a POST request to the [Initiate a transfer](/docs/api-reference/transfers/initiate-a-transfer) endpoint when sending funds from a verified Customer's balance, or to/from an unverified Customer's bank.
</ResponseField>

<ResponseField name="customer_transfer_cancelled" type="event">
  A pending transfer has been cancelled, and will not process further. Represents a cancellation of funds transferring either to an unverified Customer's bank or to a verified Customer's balance.

  **Timing:** Occurs upon a POST request to the [Cancel a transfer](/docs/api-reference/transfers/cancel-a-transfer) endpoint to cancel a transfer initiated from a verified Customer's balance, or to/from an unverified Customer's bank.
</ResponseField>

<ResponseField name="customer_transfer_failed" type="event">
  A Customer transfer failed. Represents a failed funds transfer either to an unverified Customer's bank or to a verified Customer's balance.

  **Timing:** Occurs when Dwolla marks a transfer as failed.
</ResponseField>

<ResponseField name="customer_transfer_completed" type="event">
  A Customer transfer was successful. Represents a successful funds transfer either to an unverified Customer's bank or to a verified Customer's balance.

  **Timing:** Occurs when a funds transfer into an unverified Customer's bank or a verified Customer's balance is successful, based on the transfer processing timing used.
</ResponseField>

### Customers - Mass Payments

<ResponseField name="customer_mass_payment_created" type="event">
  A verified Customer's mass payment was created.

  **Timing:** Occurs upon a POST request to the [Initiate a mass-payment](/docs/api-reference/mass-payments/initiate-a-mass-payment) endpoint.
</ResponseField>

<ResponseField name="customer_mass_payment_completed" type="event">
  A verified Customer's mass payment was completed. However, this doesn't mean that each mass payment item's transfer was successful.

  **Timing:** Occurs when a mass payment job completes.
</ResponseField>

<ResponseField name="customer_mass_payment_cancelled" type="event">
  A Verified Customer's created and deferred mass payment was cancelled.

  **Timing:** Occurs upon a POST request to the Update a mass-payment endpoint when cancelling a mass payment job.
</ResponseField>

<ResponseField name="customer_balance_inquiry_completed" type="event">
  Upon checking a Customer's bank balance, Dwolla will immediately return an HTTP 202 with response body that includes a status of `processing`.

  **Timing:** This event will be triggered when the bank balance check has completed processing.
</ResponseField>

### Customers - Labels

<ResponseField name="customer_label_created" type="event">
  A Verified Customer's label was created.

  **Timing:** Occurs upon a POST request to the [Create a label](/docs/api-reference/labels/create-a-label-for-a-customer) endpoint.
</ResponseField>

<ResponseField name="customer_label_ledger_entry_created" type="event">
  A ledger entry for a Verified Customer's label was created.

  **Timing:** Occurs upon a POST request to the [Create a label ledger entry](/docs/api-reference/labels/create-a-label-ledger-entry) endpoint.
</ResponseField>

<ResponseField name="customer_label_removed" type="event">
  A Verified Customer's label was removed.

  **Timing:** Occurs upon a POST request to the [Remove a label](/docs/api-reference/labels/remove-a-label) endpoint.
</ResponseField>