How do I Use Webhooks in the RocketReach API?

Webhooks allow you to receive real-time notifications when a person lookup or bulk lookup completes, eliminating the need to poll the API repeatedly. This guide explains how to set up, test, manage, and troubleshoot webhooks in the RocketReach API.

Key Takeaways

Webhooks automate API workflows by sending results to your server once a lookup is complete.
You must configure a callback URL in your API settings to receive webhook notifications.
Only person lookup and bulk lookup currently support webhooks.
Webhooks can be tested manually to ensure proper configuration.
You can enable, disable, or delete a webhook as needed.
Failed webhook callbacks will be retried automatically before being disabled.

What Are Webhooks in RocketReach API?

Webhooks are HTTP callbacks that automatically send data to a specified URL when an event occurs. Instead of repeatedly checking the API for results, your server will receive lookup data as soon as it’s available.

Currently, webhooks can be used for:

Person Lookup – Receive results when a single lookup completes.
Bulk Lookup – Get notified when multiple profile lookups are finished.

How to Set Up a Webhook

To configure a webhook, follow these steps:

Step 1: Log in to RocketReach

Go to RocketReach API Usage & Settings from your Account Settings
Navigate to the Webhooks section

Step 2: Enter Your Callback URL

Click Create Webhook
Enter the URL of your server where webhook notifications should be sent
Click Create

Step 3: Enable Webhook for API Requests

When performing a person lookup or bulk lookup, include your webhook ID in the API request.

Example: Using a Webhook in a Lookup Request

curl --request GET --location 'https://api.rocketreach.co/api/v2/person/lookup' \
     --header 'Api-Key: YOUR_API_KEY' \
     --data-urlencode 'name=John Doe' \
     --data-urlencode 'current_employer=Google' \
     --data-urlencode 'webhook_id=12345'

🚀 Once the lookup completes, RocketReach will send the results to your webhook URL automatically.

How to Test and Debug Webhooks

After setting up a webhook, you should verify that your server correctly receives API notifications.

Manual Webhook Test

RocketReach allows you to test webhooks by sending a sample payload.

Go to RocketReach API Usage & Settings from your Account Settings→ Webhooks
Select your webhook
Click Test Webhook
RocketReach will send a test JSON payload to your callback URL

If the test succeeds, you’ll see a 200 OK response. If it fails, check your server logs for errors.

Webhook Errors and How to Resolve Them

If RocketReach encounters issues sending data to your webhook URL, the following errors may occur:

Error Code	Description	Solution
400 Bad Request	The webhook URL is invalid.	Check the URL format and update the webhook settings.
403 Forbidden	The server rejected the request.	Ensure your server allows requests from RocketReach.
404 Not Found	The callback URL does not exist.	Verify that the URL is correct and accessible.
500 Internal Server Error	There is an issue with your server.	Check server logs for debugging.
503 Service Unavailable	The server is temporarily down.	Ensure your server is online and retry the request.

RocketReach retries failed webhooks multiple times. If your server does not respond after several attempts, the webhook will be automatically disabled, and you will need to manually re-enable it in API Settings.