Monitoring Webhooks

What It Does

Monitoring Webhooks deliver real-time HTTP notifications to your systems whenever a phone number in one of your Monitored Number lists changes TPS or CTPS status. Each list can have its own webhook URL, so different campaigns or clients can route events to different endpoints.

When a number's status changes during its automatic 28-day re-check, TPSCheck sends a POST request with a JSON payload to the webhook URL you configured. Your system receives the event instantly and can take action — update a CRM, pause a campaign, alert your team — without polling or manual checking.

Setup Steps

1. Prepare your endpoint — Set up an HTTP endpoint that accepts POST requests with a JSON body. This can be a custom server, an automation platform (n8n, Zapier, Make), or any service that exposes a webhook URL.
2. Add the URL to a list — When creating or editing a Monitored Number list, paste your endpoint URL into the Webhook URL field.
3. Test it — Click the Test button next to the URL field. TPSCheck will send a sample event to your endpoint immediately. You should see a green success message if the endpoint responds with HTTP 2xx.
4. Save the list — Click Save Changes. The webhook URL is now stored and will be used for real status change events.

Payload Format

Every webhook request is a POST with Content-Type: application/json. The JSON body contains the following fields:

{
  "event": "status_change",
  "test": false,
  "list_id": 42,
  "list_name": "Q1 2026 Campaign",
  "phone_number": "+447700900123",
  "old_tps_status": false,
  "new_tps_status": true,
  "old_ctps_status": false,
  "new_ctps_status": false,
  "change_summary": "Added to TPS",
  "timestamp": "2026-02-11T14:30:00.000000+00:00"
}

Tip: Use the test field to distinguish test events from real ones. Your system can log test events without triggering business logic.

Signature Verification (HMAC-SHA256)

When a webhook URL is saved, TPSCheck automatically generates a secret key for your list. Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the JSON payload, signed with your list's secret.

To verify the signature on your server:

1. Read the raw request body
2. Compute HMAC-SHA256 using your list's webhook secret and the body bytes (JSON keys sorted alphabetically)
3. Compare the result with the X-Webhook-Signature header value

Python example

import hmac
import hashlib
import json

def verify_webhook(request_body, secret, signature_header):
    """Verify that the webhook payload was sent by TPSCheck."""
    payload = json.loads(request_body)
    payload_bytes = json.dumps(payload, sort_keys=True).encode('utf-8')
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Node.js example

const crypto = require('crypto');

function verifyWebhook(bodyString, secret, signatureHeader) {
  const payload = JSON.parse(bodyString);
  const sorted = JSON.stringify(payload, Object.keys(payload).sort());
  const expected = crypto
    .createHmac('sha256', secret)
    .update(sorted)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Signature verification is optional but recommended for production use. It ensures the request genuinely originated from TPSCheck.

Testing Your Webhook

Using the Test button

1. Open your list settings (click the cog icon on any list)
2. Enter or confirm the Webhook URL
3. Click Test
4. A green message confirms delivery; a red message explains any errors

The test sends a sample payload with "test": true and a placeholder phone number (+441234567890).

Using curl

You can also test your endpoint directly from the command line:

curl -X POST 'https://your-endpoint-url.com/webhook' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "status_change",
    "test": true,
    "list_id": 1,
    "list_name": "Test List",
    "phone_number": "+441234567890",
    "old_tps_status": false,
    "new_tps_status": true,
    "old_ctps_status": false,
    "new_ctps_status": false,
    "change_summary": "Added to TPS (test event)",
    "timestamp": "2026-02-11T12:00:00.000000+00:00"
  }'

Troubleshooting

Key Benefits

• Real-time alerts — know immediately when a number's TPS status changes
• Per-list configuration — different lists can send to different endpoints
• Secure delivery — HMAC-SHA256 signatures verify authenticity
• Built-in testing — validate your setup before relying on it
• Platform-agnostic — works with any system that accepts HTTP POST (n8n, Zapier, Make, custom servers)
• Automation-ready — trigger CRM updates, Slack alerts, campaign pauses, and more

Monitoring Webhooks are available on Pro, Business, and Enterprise plans. Configure them from the Monitored Numbers page in your dashboard.