Using webhooks

Webhooks send near-real-time updates to your app when something changes so you don’t have to keep checking GoFundMe Pro’s APIs. Instead, your app gets the latest info through an HTTP POST request. This makes your system more efficient by cutting down on unnecessary API calls, improving performance, and keeping your data in sync.

By using webhooks, you can tailor your workflows to respond to the events that matter most. This helps you act quickly on new data, reduce resource use, and prevent errors or mismatches between systems.

Create a webhook

To create a webhook:

1. In your GoFundMe Pro account, go to Apps & Integrations and select Webhooks
2. Select Endpoints > Add Endpoint
   
3. Provide the required details:
   • Endpoint URL: The endpoint where event data will be sent
   • Description (optional): Context about the webhook’s purpose
   • Subscribe to events: Events the webhook will monitor
4. Select Create

Events and event types

GoFundMe Pro supports webhooks for events related to supporters, transactions, and recurring donations. The Event Catalog tab lists all events with example payloads, and here's a breakdown of all events:

Test webhooks

We recommend testing the webhook with sample data to confirm a stable connection and verify that your app can handle the data effectively.

To test your webhook, select the endpoint you’ve created and then select the Testing tab. Then, choose a type of event to send an example message.

After sending an example event, select the message to view its payload, all message attempts, and whether it succeeded or failed.

Troubleshoot webhooks

Webhooks can sometimes encounter issues that prevent them from working as expected. Here are some common causes of failure and how to address them.

Common errors

Unprocessed events

• Cause: Your app does not return a 2xx status code within 15 seconds.
• Solution: Make sure your endpoint responds quickly. Use async processing to acknowledge receipt immediately (return 2XX), then process the payload in the background.

Validation issues

• Cause: Webhook secret validation failing.
• Solution: Verify you're correctly validating the webhook secret from request headers. Check that you're using the correct secret key for your webhook endpoint.

Incorrect destination URL

• Cause: The endpoint URL is incorrect, not publicly accessible, or not using HTTPS.
• Solution: Verify that the endpoint URL and manually test it to confirm it accepts POST requests.

Server issues

• Cause: Your server is unreachable or not responding promptly.
• Solution: Make sure your server is reachable and capable of responding within 15 seconds. Check server logs for errors and monitor server uptime and performance.

Retries

GoFundMe Pro automatically retries failed webhook deliveries using a progressive backoff strategy. Failed deliveries are retried following our retry schedule before being removed from the delivery queue.

Visit the Svix Retry Schedule (our infrastructure provider) for detailed retry schedule information.

Unexpected transaction.updated events

You may see additional transaction.updated events that don't appear to include meaningful changes. This is expected behavior—these events result from how our system generates and queues events. In many cases, these updates do not include any meaningful changes to the payload and can be safely ignored.

We recommend comparing the payload data to determine if action is needed. If the payload hasn't changed from the previous event, you can safely discard it.

Security recommendations

• Validate webhook secret: GoFundMe Pro includes a unique secret key in webhook request headers. Always validate incoming requests against this key to ensure authenticity and prevent unauthorized access.
• Use HTTPS: Webhooks require HTTPS endpoints to ensure secure communication. Never use HTTP endpoints.
• Verify payload integrity: Use the webhook secret to verify that payloads haven't been tampered with during delivery.
• Respond promptly: Your endpoint must return a 2XX status code within 15 seconds. Consider using async processing to acknowledge receipt immediately, then process the payload in the background.

Best practices

• Implement idempotent processing: Webhooks may be retried, so make sure your processing is idempotent (safe to retry without creating duplicates).
• Use timestamps for sequencing: Events may arrive out of order, so use timestamps in payloads to determine the correct sequence.
• Log all deliveries: Log all webhook deliveries for troubleshooting and audit purposes.
• Monitor failed deliveries: Regularly check failed delivery logs to ensure your endpoint is responding correctly.
• Handle retries gracefully: Webhooks automatically retry failed deliveries—ensure your endpoint can handle retry attempts.
• Combine with polling to manage rate limits: If your integration also uses the GoFundMe Pro REST APIs, use webhooks as your primary trigger and reserve API polling for reconciliation or backfill scenarios. This helps you stay within API rate limits and avoid unnecessary requests.
   

FAQs

In what order are events sent from a webhook?

We can’t guarantee webhook events will arrive in the same order they’re created. They’re sent as separate requests, so things like network delays, retries, or server load balancing can change the order. Use each event’s ID or timestamp to determine the correct sequence instead of assuming they’ll arrive in order.

Are webhooks working in real time?

Not exactly. Webhook delivery depends on internet speed, retries after temporary errors, and how quickly systems on both sides process data. These factors can cause slight delays. Still, we’ve built our platform to process and send webhooks as quickly as possible, so you can expect near-real-time performance.

What happens if my endpoint is down?

GoFundMe Pro automatically retries failed webhook deliveries using a progressive backoff strategy. However, repeated failures over five days will result in the webhook being deactivated. Monitor your failed delivery logs and ensure your endpoint is responding correctly.

Do I need to process every event?

Some transaction.updated events may not include meaningful changes to the payload. Compare payloads to determine if action is needed. If the payload hasn't changed, you can safely ignore the event.

How do I validate webhook deliveries?

GoFundMe Pro includes a unique secret key in webhook request headers. Validate incoming requests against this key to ensure authenticity. See our section on best practices for more details.

How do webhooks help with API rate limits?

Webhooks reduce the need to repeatedly poll GoFundMe Pro's APIs for updates, which helps you stay within rate limits. Rather than making frequent API requests to check for changes, use webhooks to automatically push updates to your endpoint. If you do need to make follow-up API requests in response to a webhook event, be mindful of how many requests a single webhook event triggers, especially during high-volume periods. For current rate limit thresholds and guidance, refer to our API documentation.

Who is Svix?

GoFundMe Pro webhooks are powered by Svix, a trusted and robust webhook infrastructure provider. Svix helps ensure secure delivery, high reliability, and advanced features like automatic retries and signature verification, making it easier for you to build stable integrations.

Will you be adding new events in the future?

Please leave us your feedback to help inform our investment in the platform.