Q: What is an Event vs Webhook Subscription vs Webhook?
Event — An event is a unique resource that gets created whenever an action occurs in Dwolla that changes the state of an API resource like an external party being created or a funding source being verified.
Webhook Subscription — A webhook subscription is a resource in the API that you can create in order to subscribe to Dwolla webhooks.
Webhook — A webhook is an HTTP request that Dwolla sends to your subscribed URL to notify your app of an event. In order to get webhook notifications, you will need to have an active webhook subscription.
Q: Is a webhook subscription required to integrate with the Dwolla API?
While a webhook subscription is not required for you to integrate with the API, Dwolla requires all applications to have one in production for automated notifications of events to your application. Webhooks provide automatic near real-time status updates to your application versus polling the API which causes unnecessary load on your application and the API.
Q: How to validate that a webhook is coming from Dwolla? Is there a list of IP addresses that I can limit webhook requests from?
Dwolla includes a X-Request-Signature-SHA-256 header on each webhook request which is a SHA-256 HMAC hash of the request body with the key being the webhook secret you passed in when you created the webhook subscription. As a best practice, we recommend validating webhooks by generating the same SHA-256 HMAC hash and comparing it to the signature sent with the payload.
We do not recommend nor support relying on IP whitelisting as a method of validating webhooks. Dwolla's IPs are dynamically allocated with no defined range and are subject to change. Refer to the Processing/Validating section for a more detailed guide.
Q: Can I subscribe to certain event topics?
Dwolla sends webhooks for all events that occur in your platform and there isn’t a way to filter what events you subscribe to.
Q: How do I know if a webhook request failed and needs to be retried?
When listing all webhooks by webhook subscription, an embedded attempts array will include a response object that includes a statusCode property indicating the HTTP status code that Dwolla received when the webhook attempt was made. If the status code that Dwolla received was >=300, then the attempt was considered to have failed.
Q: Can I create more than one webhook subscription?
Yes. You can create up to 5 webhook subscriptions in Production and 10 in Sandbox. While only one subscription is needed to be notified of all events, you can have multiple in case one or more of your URLs becomes unreachable.