PublicAPI
PublicAPI copied to clipboard
DonorDrive
Webhook Spec Implementation
About
Webhooks are a great implementation for services that want to offer Fundraisees with Alerts or Notifications when donations come through. Webhooks eliminate the need for API polling, which can easily cause a buildup of web traffic when a large number of participants are being polled in an attempt to get near-instant notifications.
Streamers commonly make use of pop-up alerts from various providers that make use of Webhooks to provide as-they-happen notifications. Webhooks will make this easier for web services (that are capable of receiving HTTPS requests) to implement functionality with notifications without having to set up a process that continuously polls the API indefinitely.
Previously I've worked with Twitch, GitLab, GitHub, Patreon, IGDB, and PayPal webhooks. DonorDrive is one of the last APIs that I poll.
Twitch
A large number of Extra-Life Fundraisees seem to use Twitch as a means of reaching their audience, and the Powered by Twitch logo is present on the Extra-Life homepage. While some may use Youtube or other streaming services, I'll be referring to Twitch as an example.
Twitch conforms to the W3C WebSub Spec, and offers streamers the ability to receive near-instant POST notifications when changes are made to the results that are cached in the API. Similar functionality from DonorDrive would be extremely appreciated.
Implementation
DonorDrive does not, to my knowledge, support OAuth in any sense. Twitch Webhooks require using an OAuth token to register a webhook, while IGDB up until recently only made use of a static User-Key that was given to every developer account.
I'm not 100% if the Spec can be followed to a T, but the security around it is optimal. Prevent malicious users from creating a webhook pointed at google.com, and verify information sent to a webhook using HMAC with a user-defined key.
Personally I only use the /api/participants/{participantID}/donations endpoint for alerts, though others may be interested in other data such as team donations, or milestones.
TTL
Twitch Webhooks have a TTL of 10 days, and then must be renewed. Some of the other services' webhooks do not have a set TTL, but will disable after a limited number of non-2XX HTTP responses.
A TTL may not be necessary for DonorDrive, aside from non-2XX codes, as registrations reset every year anyway, webhooks could also do the same.
Game Day
Game Day 2020 is rapidly approaching, so I'll assume that something of this scale isn't doable this year, but may be nice to see for next year.
This is awesome. Thank you for taking the time to provide this level of detail.
This has been 2 years, does donordrive have any implementation with webhooks ?
Hi @software770 , it's still on the radar. API documentation is long overdue for an overhaul as well. Are you fundraising for EL? I'll do my best to pull some things together as soon as possible. Meantime, would love any additional insight into how webhook support would help your efforts.
@timmixell Some friends and I fundraise for extra life every year (on Game Day we get together for a LAN party), polling for the ~10 of us always felt a bit dirty.
I'd also still really like to see an OAuth flow (#45), not even really for permission reasons, but for easy validation. Asking people to type numbers into an input also felt dirty. Just click a button on my site, click another button on the EL site, and then I have all the data I need.
Would love to integrate with DonorDrive/Extralife in the future.
Completely understand being busy though, I have also been quite busy with other tasks with programming! Can't wait to see what the future brings.