How to Automate WHMCS Proposals with Webhooks

A client signs your proposal at 2 AM. You find out the next morning when you check WHMCS. By then, 8 hours have passed without a follow-up.

MX Proposals Pro includes webhooks that notify your systems the moment something happens. Proposal sent, viewed, signed, paid, declined, or expired. Each event fires an HTTP POST to your endpoint within seconds.

This guide shows you how to set up webhooks and connect them to tools you already use.

What Are Proposal Webhooks?

Webhooks are HTTP POST requests that MX Proposals sends to a URL you configure. Every time a proposal event happens, your endpoint receives a JSON payload with the event type, proposal data, and client information.

Six events are available:

Each request includes three custom headers: X-Proposals-Event (the event name), X-Proposals-Signature (HMAC-SHA256 hash for verification), and X-Proposals-Timestamp (Unix timestamp).

Setting Up Webhooks in MX Proposals

Configuration takes about 30 seconds.

1. Go to Addons > Proposals > Settings
2. Click the Automation tab
3. Enter your Webhook URL (the endpoint that will receive POST requests)
4. Optionally enter a Webhook Secret for signature verification
5. Save

That is it. Every proposal event now fires a webhook to your URL.

What Does the Payload Look Like?

Here is an example payload for proposal.accepted:

{
  "event": "proposal.accepted",
  "timestamp": 1740234567,
  "proposal": {
    "id": 42,
    "title": "Web Redesign Project",
    "status": "accepted",
    "token": "abc123def456",
    "total": "1500.00",
    "deposit": "750.00"
  },
  "client": {
    "email": "john@example.com",
    "name": "John Doe"
  }
}

The proposal object always includes the ID, title, status, token, total, and deposit. The client object appears when client data is available (on proposal.accepted for example). Some events include extra fields like order_ids (on proposal.paid) or reason (on proposal.declined).

5 Practical Automations

1. Slack Notification When a Proposal Is Signed

The most common use case. Get a message in your team channel the moment a client signs.

Setup: Point the webhook URL at a Slack Incoming Webhook. Or use n8n/Zapier as a middleman to format the message.

What you get: A Slack message like "John Doe just signed Web Redesign Project ($1,500). Deposit: $750."

Why it matters: Your team can start onboarding within minutes, not hours. The client feels the speed.

2. n8n Workflow for Proposal Follow-Ups

Connect webhooks to n8n (self-hosted or cloud) to build multi-step automations.

Example workflow:

• Trigger: proposal.viewed webhook
• Wait: 24 hours
• Check: Has the proposal been accepted?
• If no: Send a follow-up email via SMTP
• If yes: Do nothing (client already signed)

This turns your proposals into an automated sales pipeline. No manual follow-ups, no forgotten leads.

Another workflow:

• Trigger: proposal.accepted webhook
• Action 1: Create a project in your PM tool (Asana, Trello, Linear)
• Action 2: Send a welcome email to the client
• Action 3: Notify the assigned team member on Slack

3. CRM Updates on Every Event

If you use a CRM (HubSpot, Pipedrive, or even a Google Sheet), webhooks keep it in sync.

How it works: Every proposal event updates the deal status in your CRM. Proposal sent = deal created. Proposal viewed = deal active. Proposal accepted = deal won. Proposal declined = deal lost.

No manual data entry. Your CRM reflects reality without anyone touching it.

4. Discord or Telegram Alerts

Same concept as Slack, different platform. Point webhooks at a Discord webhook URL or use a Telegram bot API endpoint.

Use case: Small hosting teams that use Discord or Telegram instead of Slack. Get real-time alerts without switching tools.

5. Custom Dashboard or Analytics

Collect webhook events in a database and build your own proposal analytics.

Track: Average time from sent to viewed. Average time from viewed to signed. Decline rate and reasons. Which proposal templates convert best.

WHMCS does not track these metrics. Webhooks give you the raw data to build whatever you need.

Verifying Webhook Signatures

If you set a webhook secret, verify the X-Proposals-Signature header to confirm requests come from your WHMCS installation and not a third party.

$secret = 'your-webhook-secret';
$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256', $payload, $secret);
$received = $_SERVER['HTTP_X_PROPOSALS_SIGNATURE'];
 
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}
 
// Signature valid, process the webhook
$data = json_decode($payload, true);
$event = $data['event'];

This is optional but recommended for production use. It prevents unauthorized requests from triggering your automations.

Webhooks vs Email Notifications

MX Proposals already sends email notifications for proposal events. So why use webhooks?

Email notifications are for humans. Webhooks are for machines. Use both.

Requirements

• MX Proposals Pro plan ($25/month)
• WHMCS 8.0 or newer
• An endpoint that accepts HTTP POST requests (n8n, Zapier, custom app, or any webhook receiver)

The Free tier does not include webhooks. Upgrade to Pro to enable automation.

Getting Started

1. Download MX Proposals Free or upgrade to Pro
2. Configure your webhook URL in Settings > Automation
3. Test with webhook.site to see payloads in real time
4. Connect to your preferred tool (n8n, Zapier, Slack, custom app)
5. Read the full webhook documentation for all events and payload details

Webhooks turn MX Proposals from a document tool into an automation platform. Every proposal event can trigger whatever workflow your business needs.