Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL, and we’ll send you the details as the events take place. Configuring your server to receive a new webhook is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL. Webhooks are managed in your account dashboard. Login and navigate to ‘Webhooks’ in the left column.
We currently support either HTTP or HTTPS urls, so you can use an SSL-enabled url. We recommend this if possible. But keep in mind that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems. We advise you to guard against replay-attacks by recording which events you receive, and never processing events twice. We also recommend that you check the isTest attribute of the webhook before processing events in your production environment. Webhook data is sent as JSON in the request’s body. The full event details are included and can be used directly. If security is a concern, or if it’s important to confirm that FirstGiving sent the webhook, you should only use the ID sent in your webhook, and subsequently request the details of the event via the Verfiy endpoint below.
You can verify the entire data payload of a notification given it’s signature.
- Donation – This will fire every time you process a successful transaction
- Refund – This will fire every time a transaction is reversed
- Disbursement – This will fire when FirstGiving issues a payment to the benefiting nonprofit
All events share a common payload structure. The request will be a post, and the data will be JSON in the request’s body. Here’s a sample:
Responding to a Webhook
To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Given any response outside the 200 range, FirstGiving will continue trying to send the webhook every few minutes for 3 days. After 3 days, we’ll mark the request as failed and stop trying.
You can post a test payload from within your FirstGiving dashboard. Login and navigate to ‘Webhooks’ in the left column. If you don’t have any test webhook URLs defined, you’ll have to define one first. Then, hit test and we will post a test payload to the endpoint. The endpoint configuration will not be saved unless you press save. If you don’t have an application set up to receive webhooks but want to samples requests, we suggest using a service like RequestBin to inspect the requests we send.