Webhook Configuration Guide

What is Webhook?

Webhook allows SNSTracker to automatically send notifications to your server or application when monitored content meets your configured thresholds. For example, when a video's views increase significantly, or when a channel gains new followers, SNSTracker will send a notification to your webhook URL (typically within 1 minute).

Step-by-Step Configuration Guide

Step 1: Prepare Your Webhook Endpoint

Before configuring in SNSTracker, you need to have a webhook endpoint ready. This is a URL that can receive HTTP POST requests.

Options for your webhook endpoint:

Your own server: https://api.yourcompany.com/webhook
Cloud functions: AWS Lambda, Google Cloud Functions, Azure Functions, etc.
Automation platforms: Zapier, Make.com, n8n, etc.
Testing services: webhook.site (for testing only)

Requirements:

Must use HTTPS (URL starts with https://)
Must accept POST requests
Should return HTTP 200-299 status code for success

Step 2: Add Webhook Target in SNSTracker

Navigate to Collections page
- Log in to SNSTracker
- Click Collections in the left sidebar (under Track section)
- Or go directly to: /dashboard/collections
Open Manage Notify Targets
- On the Collections page, find and click the "Manage Notify Targets" button
- This opens the notification targets management dialog
Add a new target
- Click the "Add Target" button
- A dialog will appear for creating a new notification target
Select Webhook type
- In the dialog, find the "Type" dropdown
- Select "Webhook" from the options
Enter Webhook URL
- In the "Webhook URL" field, enter your webhook endpoint URL
- Example: https://api.yourcompany.com/webhook
- Important: The URL must start with https://
Add comment (optional)
- In the "Comment" field, you can add a note to remember what this webhook is for
- Example: "Production webhook for TikTok monitoring"
- Maximum 50 characters
Configure signature key (optional, recommended for production)
- In the "Extra" field, you can add a JSON object with a signature key:
```
{
  "signature_key": "your-secret-key-here"
}
```
- This key will be used to verify that requests are authentic
- If not provided, SNSTracker will use your API key or webhook URL as the signature key
Save the webhook target
- Click the "Save" button
- Your webhook target is now created and ready to use

Step 3: Configure Notification Rules in Collection

Open Collection settings
- Go back to the Collections page
- Find the collection you want to configure notifications for
- Click the Edit button (or click on the collection name to open settings)
Enable Feed Notify (for videos/posts)
- In the collection settings, find the "Feed Notify" section
- Toggle the "Enable Notifications" switch to ON
- Select your webhook target from the "Notify Targets" dropdown
- Choose the "Metrics" you want to monitor:
  - Views
  - Engagement (likes + comments + shares)
- Set the "Threshold" value:
  - Enter a number (e.g., 1000) to notify when the metric increases by this amount
  - Set to 0 to notify after every successful refresh
- Click "Save" or "Update"
Enable Channel Notify (for accounts)
- In the same collection settings, find the "Channel Notify" section
- Toggle the "Enable Notifications" switch to ON
- Select your webhook target from the "Notify Targets" dropdown
- Choose the "Metrics" you want to monitor:
  - Followers
  - Followings
  - Likes
- Set the "Threshold" value:
  - Enter a number (e.g., 500) to notify when the metric increases by this amount
  - Set to 0 to notify after every successful refresh
- Click "Save" or "Update"
Verify configuration
- Make sure both the webhook target and notification rules are saved
- Your webhook will now receive notifications when the configured thresholds are met

Step 4: Test Your Webhook

Use a testing service (recommended for first-time setup)
- Visit webhook.site
- Copy the unique URL provided (e.g., https://webhook.site/unique-id)
- Use this URL as your webhook URL in Step 2
- Configure a notification with threshold 0 (to trigger on any change)
- Wait for SNSTracker to check your content
- Check webhook.site to see if you received the notification
Check your endpoint logs
- If using your own server, check the server logs
- Look for incoming POST requests from SNSTracker
- Verify the request body contains the expected data
Verify notification format
- The notification should be a JSON object with:
  - title: Description of the notification
  - type: Either "feed" or "channel"
  - timestamp: When the notification was sent
  - data: Array of items that triggered the notification

How Webhook Notifications Are Sent

SNSTracker uses a batching mechanism to optimize webhook delivery:

Immediate Detection: When a monitored resource (feed or channel) is successfully refreshed and meets your notification threshold, it's immediately flagged for notification.
1-Minute Batch Window: Rather than sending individual notifications immediately, SNSTracker accumulates all eligible notifications within a 1-minute window.
Consolidated Delivery: At the end of each 1-minute period, all notifications from that window are merged into a single webhook request and sent together.

Example Scenario:

At 10:00:15, Feed A meets the threshold → flagged
At 10:00:45, Feed B meets the threshold → flagged
At 10:01:00, both Feed A and Feed B are sent in one webhook request

Benefits:

Reduces the number of HTTP requests to your endpoint
Improves efficiency and reduces server load
Prevents notification spam during rapid data changes
All notifications within the batch period are included in the data array

Note: The maximum delay between a resource meeting the threshold and the webhook being sent is 1 minute. This ensures near-real-time notifications while maintaining system efficiency.

What Data Will You Receive?

When a notification is triggered, you'll receive a POST request with JSON data like this:

{
  "title": "SNSTracker Notification: Feed Views Increased",
  "type": "feed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "feed_id": "feed-123",
      "url": "https://www.tiktok.com/@user/video/123",
      "platform_name": "TikTok",
      "view_count": 10000,
      "like_count": 2000,
      "changed_views": 1000,
      "changed_engagement": 50
    }
  ]
}

Feed Notification Data Fields

feed_id: Unique identifier
url: Direct link to the video/post
platform_name: Platform (TikTok, Instagram, etc.)
title: Content title
description: Content description
author_username: Creator's username
author_nickname: Creator's display name
view_count: Total views
like_count: Total likes
comment_count: Total comments
share_count: Total shares
changed_views: Views increased since last check
changed_engagement: Engagement increased (likes + comments + shares)

Security: Signature Verification

SNSTracker includes a signature in the X-Signature header to verify request authenticity. The signature key is determined by:

The signature_key in the Extra field (if provided)
Your first active API key (if no signature_key is set)
Your webhook URL (as fallback)

For production use, it's recommended to verify the signature to ensure requests are authentic.

Troubleshooting

Webhook not receiving notifications

Check webhook URL
- Verify the URL is correct and accessible
- Make sure it starts with https://
- Test the URL manually with a POST request
Check notification settings
- Verify notifications are enabled in your Collection
- Check that the webhook target is selected
- Ensure thresholds are set correctly
Check endpoint status
- Make sure your endpoint is running and accessible
- Check server logs for incoming requests
- Verify your endpoint returns success status (200-299)

Common Issues

Issue: "Webhook URL already exists"
Solution: Each webhook URL can only be used once per team. Use a different URL or edit the existing target.

Issue: Notifications not triggering
Solution:

Set threshold to 0 to test (notifies on any change)
Wait for SNSTracker to check your content (checking happens periodically)
Verify your content actually changed by the threshold amount

Issue: Timeout errors
Solution: Your endpoint must respond within 30 seconds. Optimize your endpoint's response time.

Need Help?

If you encounter issues:

Verify your webhook URL is accessible
Check that notification settings are enabled
Ensure thresholds are configured correctly
Contact support if problems persist

Happy tracking! 🚀