How to Set Up and Use Webhooks

Webhooks allow RatingFlow to automatically send review data to other applications or services in real-time. This is an advanced feature for developers and power users.

What are Webhooks?

A webhook is a way for RatingFlow to automatically send data to another system when something happens. When a customer submits a review, RatingFlow can instantly send that review data to a URL you specify. Think of it as RatingFlow calling another application to say 'Hey, a new review just came in, here's all the information.'

This is different from you manually checking for new reviews or exporting data. With webhooks, the data comes to you automatically the moment it happens.

Common Use Cases

Webhooks are useful for:

CRM Integration: Automatically add review data to your CRM system like Salesforce, HubSpot, or Zoho when customers leave feedback.

Slack Notifications: Send instant notifications to a Slack channel when you receive negative reviews so your team can respond quickly.

Email Alerts: Trigger custom email notifications to specific team members based on review content or rating.

Database Storage: Automatically save review data to your own database for custom reporting or analysis.

Automation Workflows: Connect to tools like Zapier, Make, or custom scripts to trigger complex workflows based on reviews.

Dashboard Updates: Push review data to internal dashboards or reporting systems in real-time.

Before You Set Up Webhooks

Webhooks are a technical feature. To use them, you need:

A webhook endpoint URL: This is a web address on your server or service that can receive POST requests with JSON data. If you're using a service like Zapier or Make, they'll provide this URL. If you're building custom integration, you'll need to create this endpoint yourself.

Technical knowledge: You should understand HTTP requests, JSON format, and how to process incoming data programmatically.

If you're not a developer, consider using integration platforms like Zapier or Make which provide webhook URLs and handle the technical details for you.

Setting Up a Webhook

To add a webhook to RatingFlow:

Step 1: Log in to your RatingFlow dashboard.

Step 2: Select the business you want to set up webhooks for from the dropdown menu in the sidebar.

Step 3: Click on Integrations in the sidebar menu.

Step 4: Find the Webhooks section. You'll see a field labeled Webhook URL.

Step 5: Paste your webhook endpoint URL into the field. This must be a complete URL starting with https://

Step 6: Click Save Changes.

Your webhook is now active. Every time someone submits a review, RatingFlow will send the data to your specified URL.

Webhook Payload Structure

When a review is submitted, RatingFlow sends a POST request to your webhook URL with JSON data structured like this:

The payload includes: event type always set to review.submitted, timestamp in ISO 8601 format showing when the review was created, business object containing business ID and name, review object with rating as a number 1 to 5, text containing the review content, type indicating if it was positive or needs attention, and any custom fields the customer filled out as key-value pairs.

Your endpoint should respond with a 200 status code to acknowledge receipt. If your endpoint returns an error or doesn't respond within 10 seconds, RatingFlow will retry the webhook up to 3 times with exponential backoff.

Testing Your Webhook

After setting up your webhook, test it:

Step 1: Visit your review page and submit a test review.

Step 2: Check your webhook endpoint to confirm it received the data. If you're using a service like Zapier or Make, check their logs. If you built custom code, check your server logs.

Step 3: Verify that all the expected data is present and correctly formatted.

Step 4: Make sure your endpoint responds with a 200 status code so RatingFlow knows the webhook was successful.

If the webhook isn't working, double-check your URL is correct, your endpoint is publicly accessible, it accepts POST requests, and it responds within 10 seconds.

Security Considerations

Webhooks expose your endpoint to incoming data. Follow these security practices:

Use HTTPS: Always use https:// URLs, never http://. This encrypts data in transit.

Validate Input: Don't blindly trust incoming data. Validate that it matches the expected format before processing.

Rate Limiting: Implement rate limiting on your endpoint to prevent abuse.

Unique Endpoints: Use a unique, hard-to-guess URL for your webhook rather than something obvious like yourdomain.com/webhook.

Error Handling: Handle errors gracefully. Don't expose sensitive information in error messages.

Monitor Activity: Keep logs of webhook activity to detect any unusual patterns.

Using Zapier or Make

If you're not a developer, integration platforms make webhooks accessible:

For Zapier: Create a new Zap, choose Webhooks by Zapier as the trigger, select Catch Hook, copy the webhook URL provided, paste it into RatingFlow's webhook field, submit a test review to send data to Zapier, then continue building your Zap to send the data wherever you want.

For Make: Create a new scenario, add a Webhooks module as the first step, choose Custom Webhook, create a new webhook and copy the URL, paste it into RatingFlow, send a test review, then add additional modules to process the data.

These platforms handle all the technical details and let you connect to thousands of other apps without writing code.

Troubleshooting

Common webhook issues and solutions:

Webhook not firing: Verify the URL is correct and saved. Make sure your endpoint is publicly accessible from the internet.

Endpoint returns errors: Check your server logs to see what's wrong. Make sure your code can handle the JSON payload format RatingFlow sends.

Timeouts: If your endpoint takes longer than 10 seconds to respond, it will time out. Optimize your code or process the data asynchronously.

Missing data: Ensure you're parsing the JSON correctly and accessing the right field names.

Removing a Webhook

To disconnect your webhook, go to Integrations, find the Webhook URL field, delete the URL, and click Save Changes. RatingFlow will immediately stop sending data to that endpoint.