Setting Up IPQualityScore Phone Number Validation Webhook

What it does#

The IPQualityScore Phone Number template sends the caller's phone number to IPQualityScore and returns validation and risk data: whether the number is valid, a fraud score, carrier, line type and related reputation fields. Store the results on the call as custom tags and use them in tag filters to screen or route calls.

It is one of five Data Collection templates: GoHighLevel, IPQualityScore Phone Number, IPQualityScore Proxy, Searchbug and Trestle. For visitor IP and proxy checks use IPQualityScore Proxy.

Prerequisites#

• An active IPQualityScore account with an API key and phone validation credits. IPQualityScore bills its own lookups; CallGrid does not.
• The custom tags you want to write results into, created first under Integrations > Tags (for example IpqsFraudScore, IpqsValid, IpqsLineType, IpqsCarrier). Tag names are case sensitive.

Set up the webhook#

1. Go to Integrations > Webhooks and click New Webhook.
2. Enter a Name.
3. Choose the Event. For screening before routing use Call Inbound. The 13 events are Call Inbound, Call Initiated, Call Ended, Call Error, Call Answered, Call Billable, Call Paid, Call Converted, Insights Completed, Transcription Completed, Recording Completed, Bid Received and Postback Received.
4. Set Template Mode to Data Collection (5) and pick IPQualityScore Phone Number.
5. Enter your IPQualityScore API key where the template asks for it.
6. Optionally set Timeout ("Configure the timeout for the webhook request"; default 5 seconds).
7. Click Save Webhook.
8. Attach it: open the campaign, General tab, add the webhook under Webhooks, and save. A webhook fires only on campaigns it is attached to.

Request#

Options in the editor:

• Authorization: fetch an OAuth access token before the request. Not needed for IPQualityScore, which uses the API key in the request.
• Use Static IP for requests: sends from 3.232.249.88 and 54.160.65.103 for endpoints that allowlist IPs. Not normally required.

Filtering, testing and value extraction#

• Tag filters limit which calls trigger the lookup, which saves credits. For example skip internal test numbers or sources that are already screened. Groups combine with AND or OR (click the operator badge to toggle).
• Testing: open the saved webhook, enter test values (a real phone number) under Webhook Testing, and click Run Webhook. Review the response to see available properties.

Using the results:

• Route high-risk callers to a lower-value group, or reject them, with a routing group filter such as IpqsFraudScore greater than 85.
• Report on the tags in Call History columns.
• For numbers that should never route again, add them to Numbers > Blocked Numbers or via POST /api/blocked.

Behavior to know#

• CallGrid does not retry a failed webhook. A timeout or error leaves the result tags empty, so routing rules that depend on them should handle an empty value (for example with an is empty condition).
• Webhook authentication to third parties is whatever the request carries; CallGrid does not sign webhooks with HMAC.

Best practices#

• Filter the webhook so trusted traffic does not spend credits.
• Extract only fields you will filter or report on.
• Test with several number types (mobile, landline, VoIP, invalid) before routing on the results.
• Watch credit consumption in IPQualityScore.

Troubleshooting#

Do it with AI#

Ask Griddy, Claude or ChatGPT. Try: "What fraud score did IPQualityScore return on my last five calls?" Claude and ChatGPT need the CallGrid connector turned on (setup guides for Claude and ChatGPT).

The connector is read only. It looks things up and reads your data. You make the changes in CallGrid.