Webhooks

Introducing GiveWP Webhooks

The GiveWP Webhooks add-on allows your website to communicate with other web-connected applications in real time by sending notifications. Those notifications – or webhooks – get sent whenever specific events happen on your website. 

Get the Webhooks Add-on View Add-on

Any system that can receive events via webhooks is fair game. Need to send something very specific to your Donor Relationship Management software? No problem. 

Want to create a mobile app that updates your team in real time when a donor (or site admin) makes changes to a Recurring Donation? Done.

GiveWP’s Webhooks add-on provides the data exactly when you need it, and alerts you when a webhook endpoint is failing. 

With webhooks, you can specify which events send data to third-party integrations so that you can tailor your integrations to your precise needs. 

Getting Started with the Webhooks Add-on

Installing the GiveWP Webhooks Add-on

The Webhooks add-on extends the power and functionality of GiveWP, so it needs to be installed on your WordPress website along with the GiveWP plugin. Learn more about installing GiveWP add-ons.

Setting up the Webhooks Add-on

There are no settings for the Webhooks add-on. Once you’ve installed and activated it, an additional page shows up in the GiveWP Tools section of the back end of your site. Navigate to Donations > Tools > Webhooks. 

On the first visit, you’ll see a blank table with the ability to add endpoints. Once you’ve added endpoints, any subsequent visits will display the endpoints, how many events are sent to that specific endpoint, its status, and some action buttons to edit or delete each endpoint.

Use the Add endpoint button to add an endpoint. 

On the popup modal, add an Endpoint URL, which is the URL listening for GiveWP events. Optionally, you can write a description to describe what the endpoint will be used for so you can keep track of them more easily. The dropdown on the bottom of the modal lists all of the available events.

Use the Add Endpoint button to save the endpoint and return to the previous screen. 

Note the new webhook added, along with a few columns:

• Active: a toggle to click to make it active or inactive
• URL: your webhook URL
• Events Sent: the number of events you are sending to that endpoint
• Status: the status of your webhook events (working or failing)
• Actions: edit and delete

That’s it! Webhooks is all set up, and running in the background!

Understanding How The Webhooks Add-on Works

What events are eligible to be sent over the webhook?

The best way to know which events are possible is to view them on the dropdown on the modal, as described above. If you don’t see the event that you need, definitely reach out to the GiveWP support team to request a new event. Compatibility with more add-ons is on the list of things to do, and the more folks request functionality, the more likely it gets prioritized.

What data is sent for each event? Is that data logged somewhere?

Baked into GiveWP’s Webhooks add-on is helpful logging, and the logs are the best place to discover what data is sent for each event. To see those logs, navigate to Donations > Tools > Logs. 

By default the Webhooks add-on only logs failed requests. If you want to simulate that, create a webhook with an invalid endpoint URL (any string of text that’s not a URL will do). To enable logging for *all* requests, successful or not, enable WP_DEBUG_LOG in your wp-config.php file. Read more about DEBUG mode in WordPress here.

Note that this can result in very large log database tables, so you’ll want to establish a workflow of flushing the logs routinely, if you leave WP_DEBUG_LOG enabled for any long period of time, especially on a high-traffic site. 

With verbose logging enabled, you can see all of the data sent for every event type by triggering that event and then checking the log. Use the eye icon to see the full log output. 

What if an endpoint fails?

By default, the add-on will try to send each request to your endpoint five times. GiveWP uses Action Scheduler which helps to more reliably run background processes. The first action is set to run immediately. If that one fails the retry runs 1 second later. The third attempt (in the event the first two fail) is 5 minutes later, then 15 minutes, and finally 1 hour later. 

To customize the number of retries, use the givewp_webhooks_retries_for_requests filter to change how it works or even add more retries into the system.

Here’s an example code snippet that adds two additional retries, one at 2 hours, and one at 1 day:

add_filter('givewp_webhooks_retries_for_requests', function(){
    return [  
              '+1 second',
              '+5 minutes',
              '+15 minutes',
              '+1 hour',
              '+2 hours',
              '+1 day',
    ]; 
});

Need help adding PHP snippets to your site? Read the tutorial on that.

After five failures (one initial and 4 retries… or however many you added using the code snippet above) GiveWP triggers an email notification to alert site admins of the failing endpoint. If events fail for a week, the webhook is deactivated automatically, and GiveWP triggers another email notification explaining how to resolve the issue.

Possible Integrations with Webhooks

Many tools can receive notifications from webhooks, but here are a few you might already use that have documented support for webhooks. While setting up these integrations may require some help from a developer familiar with the platform, there’s at least some system already in place for handling webhooks, and some documentation to that end:

• Microsoft Dynamics 365
• Microsoft Power Platform
• Pabbly
• CiviCRM

The true power of webhooks of course is that you can send them to any internet-connected thing, as long as you know how to code the appropriate webhook listener!

FAQ