Webhooks

Getting Started

Create your webhook

Go to your RocketReach account API Usage & Settings page

Enter your webhook's URL and check the endpoints you wish to enable, then click Create.

Make sure the webhook is enabled and click Test Webhook to verify connection

Send a lookup request

Create either a People Lookup or Bulk People Lookup request and include your desired webhook's ID in the request parameters. If no webhook ID is provided in the request, the value will default to your top-most enabled webhook.

Request Query Examples

People Lookup API

{
  "id": 123456,
	"webhook_id": 1004,
}

Bulk People Lookup API

{
  "queries": [

		{"id": 123456}, ...
  ],
	"webhook_id": 1004,
}

Get response data

Response data sent to webhooks will always have the following format (or a list of these objects for bulk requests)

{
	"profile_list": {
      "id": 1000,
      "name": "Example Profile List"
  },
  "id": 123456,
	...
}

With headers

{
  "RR-Request-ID": "85c36d54-8c43-4a97-8a7d-782d8a0f938f",
	...
}

Use this RR-Request-ID to correlate your requests with responses received by the webhook

Authentication

Generate a webhook secret

Go to your RocketReach account API Usage & Settings page and find/create your webhook

Click Generate Secret or Regenerate Secret and await confirmation of a successful generation

Store the secret value for future use in authentication

Verify your webhook data

Your response data will now contain the following header

{
  "X-RocketReach-Signature": "h50yogIFeOJuOvaxOoJhtJ2WHOzqdKFsGG7p4f3lkwI=",
	...
}

Using your secret and the raw response body you can compute an expected secret value using the following code example

import hashlib
import hmac
import base64

def verify_signature(secret, body, received_signature) -> bool:
	# secret: the secret associated with your webhook ID
	# body: the raw response body (bytes) recieved from RocketReach
	# received_signature: 'X-RocketReach-Signature' from the recieved headers
  # Compute HMAC-SHA256 of the body
  computed_hmac = hmac.new(
    secret.encode("utf-8"),
    body,
    hashlib.sha256
	).digest()
  # Base64 encode the result
  computed_signature = base64.b64encode(computed_hmac).decode("utf-8")
  # Use constant-time comparison to avoid timing attacks
  return hmac.compare_digest(computed_signature, received_signature)

A True response indicates the response was properly authenticated