Webhooks

What are Webhooks?
Webhooks are automated messages sent from Solar Proof to your server when specific events occur. Instead of constantly polling our API for updates, webhooks push data to you instantly when something happens.

How Webhooks Work

Subscribe: Register your webhook URL and specify which event types you want to receive
Events Occur: When relevant actions happen in Solar Proof (customer created, email sent, etc.), we trigger the webhook
Receive Data: Solar Proof sends an HTTP POST request with event data to your webhook URL
Process: Your application receives and processes the webhook payload
Respond: Your server responds with a 200 status code to acknowledge receipt

Available Webhook Events

Event Type	Description	Status
`customer_created`	Triggered when a new customer is created in the system	Active
`customer_status_change`	Triggered when a customer's status changes (New Contacts, Signed, Mega Status)	Active
`project_email_sent`	Triggered when a project email is sent to a customer	Active
`project_sms_sent`	Triggered when a project SMS is sent to a customer	Active
`published_proposal_link`	Triggered when a proposal link is published for a project	Active
`recent_draft_project`	Triggered when a draft project is created or updated	Active

Quick Start Guide

1. Set Up Your Webhook Endpoint

Create an endpoint on your server that can receive POST requests:

Example Node.js/Express endpoint javascript

app.post('/webhooks/solarproof', (req, res) => {
    const event = req.body;
    console.log('Received webhook:', event);
    
    // Process the event
    // ...
    
    // Respond with 200 OK
    res.status(200).send('Webhook received');
});

2. Subscribe to Events

Use the subscribe endpoint to register your webhook URL:

Subscribe to customer_created events bash

curl -X POST "https://solarproof.com.au/apidata.php?action=subscribe_customer&api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hookUrl": "https://your-domain.com/webhooks/solarproof",
    "type_request": "customer_created"
  }'

3. Handle Incoming Webhooks

Process the event data and respond promptly (within 5 seconds) with a 200 status code.

Important: Your webhook endpoint must respond with a 200 HTTP status code within 5 seconds. If your endpoint takes longer or returns an error, Solar Proof may retry the webhook delivery.

Webhook Security

To ensure webhook requests are genuinely from Solar Proof:

Use HTTPS: Always use HTTPS URLs for your webhook endpoints to ensure data is encrypted in transit
Validate Source: Check that requests come from Solar Proof's IP addresses
Verify Data: Validate the structure and content of webhook payloads before processing
Use Authentication: Include authentication tokens in your webhook URL if needed

Best Practices

Respond Quickly: Acknowledge receipt immediately (return 200) and process data asynchronously
Handle Retries: Be prepared to receive the same webhook multiple times (idempotency)
Log Everything: Keep logs of all webhook deliveries for debugging and auditing
Test Thoroughly: Test your webhook handlers in a development environment before going live
Monitor Health: Set up monitoring to alert you if your webhook endpoint goes down
Use Queues: For complex processing, queue webhook events for background processing

Common Use Cases

CRM Integration

Sync customer data to your CRM when customers are created or their status changes.

Slack Notifications

Send team notifications to Slack when proposals are published or contracts are signed.

Email Automation

Trigger follow-up email sequences in your marketing automation platform.

Analytics Tracking

Send event data to analytics platforms to track customer journey and conversion rates.