Webhooks Configuration

Webhooks allow you to automatically send data to external services whenever key events happen in WisePub. Whether you want to notify your CRM when a new subscriber joins, trigger automations when announcements are published, or track webinar registrations in real-time, webhooks provide a powerful way to connect WisePub with your existing tools.

What Are Webhooks?

A webhook is an automated message sent from WisePub to another application when something specific happens. Instead of manually exporting data or checking for updates, webhooks instantly push information to your chosen destination the moment an event occurs.

Common use cases include:

• Sending new subscriber data to your CRM (HubSpot, Salesforce, etc.)
• Triggering email sequences when users join a subscription
• Logging announcement activity to Slack or Discord
• Tracking webinar registrations in your marketing automation platform
• Syncing user activity with custom applications

Understanding Webhook Types in WisePub

WisePub supports two categories of webhooks, each serving different purposes:

Global Webhooks (Admin Panel)

These webhooks respond to platform-wide events:

• Announcement Published – Triggered when any announcement is posted
• User Joined Subscription – Triggered when a user is added to a subscription
• User Left Subscription – Triggered when a user is removed from a subscription

Room Webhooks (Per-Room Configuration)

These webhooks respond to room-specific attendee activities:

• Room Registration – Triggered when a user registers for a room
• Watch Time – Triggered when user watch duration is tracked
• Minimum Watch Time – Triggered when a user meets the watch time threshold

---

Setting Up Global Webhooks

Prerequisites

• Administrator access to the WisePub Nova admin panel
• A destination URL that can receive webhook data (see Testing Tips section)

Step 1: Access the Webhooks Section

Objective: Navigate to the webhook management area in the admin panel.

1. Log in to your WisePub admin panel (Nova)
2. In the left sidebar, locate and click Webhooks
3. Click the Create Webhook button in the top right corner

Expected Result: You will see the webhook creation form with fields for name, URL, event type, and optional filtering options.

Step 2: Configure Your Webhook

Objective: Set up the webhook with your destination URL and event trigger.

Fill in the following fields:

1. Name – Enter a descriptive name for this webhook (e.g., “HubSpot New Subscriber Alert” or “Slack Announcement Notifications”)
2. URL – Enter the full destination URL where WisePub should send data. This is typically provided by your receiving application (e.g., https://hooks.zapier.com/hooks/catch/123456/abcdef/)
3. Event Type – Select when this webhook should trigger:
   • Announcement Published – Fires when announcements are posted
   • User Joined Subscription – Fires when users are added to subscriptions
   • User Left Subscription – Fires when users leave or are removed from subscriptions
4. Secret (Optional) – Add a secret key to authenticate webhook requests. When provided, WisePub will:
   • Sign the webhook payload using this secret
   • Include an APIKEY header with this value
   • Add a Signature header for payload verification
5. Announcement Type (Conditional) – Only appears for “Announcement Published” events. Select a specific announcement type to filter triggers, or leave blank to receive webhooks for all announcement types.
6. Subscription (Optional) – Filter webhooks to only trigger for a specific subscription, or leave blank to trigger for all subscriptions.

Expected Result: A configured webhook ready to receive events based on your specified criteria.

Step 3: Save and Test

Objective: Activate your webhook and verify it works correctly.

1. Click Create Webhook to save your configuration
2. Perform a test action (e.g., publish a test announcement or add yourself to a subscription)
3. Check your receiving application to confirm the data arrived

Pro Tip: Use a webhook testing service like Webhook.site or RequestBin during initial setup to inspect the exact payload WisePub sends before connecting to your production systems.

---

Setting Up Room Webhooks

Room webhooks allow you to track attendee engagement for individual rooms or webinars.

Prerequisites

• Administrator access to the WisePub Nova admin panel
• Attendee tracking enabled for the room
• A destination URL that can receive webhook data

Step 1: Access Room Settings

Objective: Navigate to the room configuration where you want to add webhooks.

1. In the Nova admin panel, click Rooms in the left sidebar
2. Locate and click on the room you want to configure
3. Click Edit to modify the room settings

Expected Result: The room editing form opens with all configuration options visible.

Step 2: Configure Room Webhooks

Objective: Add one or more webhook URLs to receive room event data.

1. Scroll to the Webhooks section in the room settings
2. Click Add a webhook
3. Enter a name for the webhook (e.g., “CRM Registration Sync”)
4. Enter the destination URL
5. Repeat to add additional webhooks if needed

Expected Result: The room is configured to send webhook notifications when attendees register or meet watch time thresholds.

Step 3: Enable Attendee Tracking

Objective: Ensure the room is configured to track the events that trigger webhooks.

Verify these settings are enabled for your room:

• Track Attendees – Must be enabled for registration webhooks
• Allow Register – Required if you want registration webhooks for non-authenticated users
• Require Email For Attendees – Recommended to ensure webhook payloads include email addresses

Pro Tip: Room webhooks only fire when a new subscriber is created. Repeat visits from the same user will not trigger additional webhooks.

---

Webhook Payload Reference

Announcement Webhooks

When an announcement is published, the receiving system receives this data:

{
    "id": 1234,
    "app_name": "WisePub",
    "app_url": "https://yourapp.wisepub.com",
    "title": "Market Update: Q4 Analysis",
    "subject_line": "Important: Q4 Market Analysis Now Available",
    "content": "We've just released our comprehensive Q4 market analysis...",
    "html_content": "<p>We've just released our comprehensive Q4 market analysis...</p>",
    "published_at": "2026-01-09T14:30:00Z",
    "published_by": "John Smith",
    "is_public": false,
    "room": "Premium Trading Room",
    "type": "Market Alert",
    "subscription": {
      "id": 5,
      "name": "Premium Membership",
      "slug": "premium-membership"
    },
    "announcement_subscriptions": [
      {
        "id": 5,
        "name": "Premium Membership"
      },
      {
        "id": 8,
        "name": "VIP Access"
      }
    ],
    "push": true,
    "email": true,
    "sms": false,
    "webhook_enabled": true,
    "meta": {
      "trade_details": {
        "ticker": "AAPL",
        "action": "BUY",
        "price": "185.50"
      }
    }
  }

Field	Description
id	Unique announcement identifier
app_name	Your WisePub application name
app_url	Your WisePub application URL
title	Announcement title
subject_line	Email subject line
content	Plain text content (HTML stripped)
html_content	Full HTML content
published_at	Publication timestamp
published_by	Name of the user who published
is_public	Whether the announcement is public
room	Associated room name (if applicable)
type	Announcement type label
subscription	Webhook-associated subscription details
announcement_subscriptions	All subscriptions receiving this announcement
push	Whether push notification was enabled
email	Whether email notification was enabled
sms	Whether SMS notification was enabled
webhook_enabled	Whether webhook was enabled for this announcement
meta	Additional metadata (including trade_details if extraction is enabled)

Subscription Event Webhooks

When a user joins or leaves a subscription:

{
    "event_type": "subscription.joined",
    "event_label": "User Joined Subscription",
    "app_name": "WisePub",
    "app_url": "https://yourapp.wisepub.com",
    "timestamp": "2026-01-09T14:30:00Z",
    "subscription": {
      "id": 5,
      "name": "Premium Membership",
      "slug": "premium-membership",
      "sku": "PREM-001",
      "description": "Access to all premium content and features"
    },
    "user": {
      "id": 789,
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "created_at": "2025-06-15T10:00:00Z"
    },
    "pivot": {
      "start_date": "2026-01-09",
      "end_date": "2027-01-09",
      "active": true
    }
  }

Field	Description
event_type	Either subscription.joined or subscription.left
event_label	Human-readable event description
app_name	Your WisePub application name
app_url	Your WisePub application URL
timestamp	ISO 8601 timestamp of the event
subscription.id	Subscription identifier
subscription.name	Subscription name
subscription.slug	URL-friendly subscription identifier
subscription.sku	Product SKU (if configured)
subscription.description	Subscription description
user	Complete user profile (excluding sensitive data)
pivot.start_date	Subscription start date
pivot.end_date	Subscription end date (if applicable)
pivot.active	Whether the subscription is active

Room Event Webhooks

When attendees interact with rooms:

Room Registration Webhook Payload
{
    "app_name": "WisePub",
    "app_url": "https://yourapp.wisepub.com",
    "room_url": "https://yourapp.wisepub.com/rooms/live-trading-webinar",
    "room_name": "Live Trading Webinar",
    "room_id": 42,
    "email": "attendee@example.com",
    "name": "Mike Johnson",
    "campaign_event": "room_registration",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "january-webinar",
    "utm_term": null,
    "utm_content": "cta-button",
    "tracked_parameters": {
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "january-webinar",
      "utm_content": "cta-button",
      "ref": "partner123"
    },
    "session_id": 101,
    "session_name": "January Trading Session",
    "session_starts_at": "2026-01-15T18:00:00Z",
    "session_ends_at": "2026-01-15T19:30:00Z",
    "session_effective_start": "2026-01-15T17:45:00Z",
    "session_effective_end": "2026-01-15T19:45:00Z"
  }

Room Watch Time Webhook Payload

  {
    "app_name": "WisePub",
    "app_url": "https://yourapp.wisepub.com",
    "room_url": "https://yourapp.wisepub.com/rooms/live-trading-webinar",
    "room_name": "Live Trading Webinar",
    "room_id": 42,
    "email": "attendee@example.com",
    "name": "Mike Johnson",
    "campaign_event": "minimum_watch_time",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "january-webinar",
    "utm_term": null,
    "utm_content": null,
    "tracked_parameters": {},
    "session_id": 101,
    "session_name": "January Trading Session",
    "session_starts_at": "2026-01-15T18:00:00Z",
    "session_ends_at": "2026-01-15T19:30:00Z",
    "session_effective_start": "2026-01-15T17:45:00Z",
    "session_effective_end": "2026-01-15T19:45:00Z",
    "total_watch_duration_seconds": 3600,
    "watch_end_timestamp": 1736964600,
    "guest_id": null
  }

Field	Description
app_name	Your WisePub application name
app_url	Your WisePub application URL
room_url	Direct link to the room
room_name	Room name
room_id	Room identifier
email	Attendee email address
name	Attendee name
campaign_event	Event type (room_registration, watch_time, or minimum_watch_time)
utm_source	UTM source parameter (if provided)
utm_medium	UTM medium parameter (if provided)
utm_campaign	UTM campaign parameter (if provided)
utm_term	UTM term parameter (if provided)
utm_content	UTM content parameter (if provided)
tracked_parameters	All tracked URL parameters

Session fields (when a room session is active):

Field	Description
session_id	Session identifier
session_name	Session name
session_starts_at	Scheduled start time
session_ends_at	Scheduled end time
session_effective_start	Actual start time (with buffer)
session_effective_end	Actual end time (with buffer)

Watch time fields (for watch_time and minimum_watch_time events):

Field	Description
total_watch_duration_seconds	Total seconds watched
watch_end_timestamp	Unix timestamp when tracking ended
guest_id	Guest identifier (if not logged in)

---

Enabling Webhooks for Announcements

By default, you must enable webhooks for each announcement you publish. Here is how to configure this behavior:

Option 1: Manual Selection Per Announcement

When creating an announcement, check the Webhook checkbox (or your custom label) to trigger webhooks for that specific announcement.

Option 2: Enable Webhooks by Default

To automatically enable webhooks for all announcements:

1. Go to Settings > General in the Nova admin panel
2. Locate the Alerts and Services section
3. Enable Enable Webhook Notifications in Announcement Form to show the webhook option
4. Optionally enable Enable Webhook Notifications By Default to pre-check the webhook option for all new announcements
5. Use Rename Webhook Checkbox to customize the label if desired (e.g., “Sync to CRM”)

Expected Result: The announcement form will display the webhook option, either unchecked or pre-checked based on your settings.

---

Security and Authentication

Using Webhook Secrets

When you configure a secret for your webhook, WisePub provides two authentication mechanisms:

1. Signature Header – A cryptographic signature of the payload using your secret, sent in the Signature header
2. API Key Header – Your secret value sent in the APIKEY header

Your receiving application can verify webhook authenticity by:

• Validating the signature matches the payload
• Checking the API key matches your expected value

Pro Tip: If you do not configure a secret, webhooks are sent unsigned. While simpler to set up, this provides no protection against spoofed requests.

SSL Verification

By default, WisePub verifies SSL certificates when sending webhooks. Ensure your destination URL uses a valid HTTPS certificate.

---

Troubleshooting Tips

Webhooks Not Firing

1. Check event type – Verify your webhook is configured for the correct event type
2. Verify subscription filter – If you set a subscription filter, ensure the event involves that specific subscription
3. Check announcement type filter – For announcement webhooks, verify the type filter matches
4. Confirm webhook checkbox – When publishing announcements, ensure the webhook option is checked
5. Review destination URL – Confirm the URL is correct and accessible from WisePub servers

Testing Your Webhooks

Use these free services to inspect webhook payloads during setup:

• Webhook.site – Provides a temporary URL to receive and inspect webhooks
• RequestBin – Similar service for webhook testing
• ngrok – Creates a tunnel to your local development environment

Webhook Retry Behavior

If a webhook fails (destination unreachable or returns an error):

• WisePub retries up to 3 times
• Each retry uses an exponential backoff strategy (increasing delays between attempts)
• If all retries fail, the webhook is abandoned

Checking Webhook Logs

Administrators can monitor webhook activity in the Laravel Horizon dashboard. Look for jobs in the default queue related to webhook processing.

---

Summary

Webhooks provide a powerful way to connect WisePub with your external tools and automations. Key points to remember:

• Global webhooks handle announcement and subscription events across your entire platform
• Room webhooks track attendee engagement for specific rooms
• Always test with a webhook inspection service before connecting to production systems
• Use secrets for authentication when security is important
• Filter webhooks by subscription or announcement type to reduce noise

With webhooks configured, your WisePub data flows automatically to wherever you need it, saving time and ensuring your systems stay synchronized.