Setting Up Blacklist Alliance Caller ID Lookup Webhook

This article is general information about CallGrid features. It is not legal advice. Talk to your own counsel about how the TCPA, state laws and Do Not Call rules apply to your business.

What it does#

The Blacklist Alliance template checks the caller's phone number against Blacklist Alliance's litigator and complainer databases before a call reaches a buyer, as one part of your own screening process. Results can be saved to custom tags for routing, or used to reject the call.

It is one of four Caller Id Lookup templates: Blacklist Alliance, Contact Center Compliance, TCPA Litigator List and TrustedForm.

Prerequisites#

• An active Blacklist Alliance account and API key. Blacklist Alliance bills its own lookups.
• Custom tags for any results you want to keep, created under Integrations > Tags (for example BlacklistResult). 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. 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. For screening:
   • Call Inbound runs before routing and is the natural place to tag callers.
   • A Call Inbound webhook can also reject calls. At that point the buyer and destination are not yet known, so the rejection cannot depend on buyer or destination tags; a caller number lookup like Blacklist Alliance does not need them.
   • On bidding campaigns, screening at bid time uses Bid Received.
4. Set Template Mode to Caller Id Lookup (4) and pick Blacklist Alliance.
5. Enter your Blacklist Alliance API key where the template asks for it.
6. Optionally set Timeout (default 5 seconds).
7. Click Save Webhook.
8. Attach it: campaign > General tab > Webhooks, add it and save. A webhook fires only on campaigns it is attached to.

Filtering, testing, value extraction and rejection#

• Tag filters decide which calls trigger the lookup, for example skip sources already screened upstream. Filter groups combine with AND or OR: "Click the operator badges to toggle between AND/OR."
• Testing: open the saved webhook, enter test values under Webhook Testing, and click Run Webhook; check the response contains the lookup result.
• Rejection: acceptance parsing on the response can reject the call when the number is flagged. Rejection Protection ("Do not reject the call or bid if the webhook http status code is not 200") keeps calls flowing if Blacklist Alliance is down.

Using the results:

• Reject or reroute flagged callers.
• Add confirmed litigators to Numbers > Blocked Numbers (universal or per campaign) or with POST /api/blocked, so later calls are rejected before routing without a paid lookup.

Behavior to know#

• CallGrid does not retry failed webhooks. A timeout leaves result tags empty; decide whether empty means allow or block and build filters accordingly.
• CallGrid does not sign webhooks with HMAC.
• A lookup service reduces risk; it does not guarantee TCPA compliance.

Best practices#

• Test with known flagged and clean numbers before going live.
• Filter to avoid paying for lookups on trusted traffic.
• Keep the timeout short so screening does not delay routing noticeably.
• Keep the API key current; rotate it in the webhook if it changes.

Troubleshooting#

Do it with AI#

Ask Griddy, Claude or ChatGPT. Try: "Which of my campaigns have the Blacklist Alliance webhook attached, and what did it return on my last call?" 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.