Integration Guide
Webhooks
Receive real-time HTTP notifications when new testimonials are submitted. Perfect for triggering automation, sending alerts, or syncing with your CRM.
What are Webhooks?
Webhooks are automated HTTP POST requests sent to your server when specific events occur. When someone submits a testimonial, ProofLayer can instantly notify your application with the testimonial data.
Think of webhooks as "reverse APIs" - instead of your application polling our API for updates, we push updates to you in real-time.
Real-time
Instant notifications within seconds of submission
Secure
Signed with HMAC for authenticity verification
Reliable
Automatic retries with exponential backoff
Setup Guide
Create an endpoint
Set up an HTTPS endpoint on your server to receive webhook POST requests.
app.post('/webhooks/prooflayer', async (req, res) => {
const payload = req.body;
// Process the webhook
console.log('New testimonial:', payload);
// Respond quickly (200 OK)
res.status(200).send('Received');
// Handle async tasks after responding
await processTestimonial(payload);
});Add webhook URL to dashboard
In your workspace settings, navigate to Webhooks and add your endpoint URL.
Save your signing secret
Copy the webhook signing secret from the dashboard. You'll use this to verify webhook authenticity.
Keep your signing secret secure
Store it as an environment variable - never commit it to version control.
Test your webhook
Click "Send test webhook" to verify your endpoint is working correctly.
Payload Structure
Each webhook delivers a JSON payload with the following structure:
{
"event": "testimonial.submitted",
"timestamp": "2026-01-22T14:30:00Z",
"workspace_id": "ws_abc123",
"form_id": "frm_xyz789",
"testimonial": {
"id": "test_def456",
"type": "text",
"content": "Amazing product! Highly recommend.",
"rating": 5,
"author": {
"name": "Jane Doe",
"email": "jane@example.com",
"company": "Acme Corp",
"title": "Product Manager"
},
"metadata": {
"ip_address": "192.0.2.1",
"user_agent": "Mozilla/5.0...",
"referrer": "https://google.com"
},
"submitted_at": "2026-01-22T14:30:00Z"
}
}| Field | Type | Description |
|---|---|---|
| event | string | Event type (currently only "testimonial.submitted") |
| timestamp | ISO 8601 | When the webhook was sent |
| testimonial.type | string | "text", "video", or "screenshot" |
| testimonial.rating | number | Star rating (1-5, null if not provided) |
Signature Verification
All webhooks include a signature in the X-ProofLayer-Signature header. Verify this to ensure the request came from ProofLayer.
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(JSON.stringify(payload)).digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(digest)
);
}
// In your endpoint
app.post('/webhooks/prooflayer', (req, res) => {
const signature = req.headers['x-prooflayer-signature'];
const secret = process.env.PROOFLAYER_WEBHOOK_SECRET;
if (!verifyWebhook(req.body, signature, secret)) {
return res.status(401).send('Invalid signature');
}
// Process webhook...
res.status(200).send('OK');
});Always verify signatures
Without verification, malicious actors could send fake webhook requests to your endpoint. Always validate the signature before processing the payload.
Retry Logic
If your endpoint doesn't respond with a 2xx status code, ProofLayer will automatically retry the webhook using exponential backoff:
- Immediately: First retry after 1 second
- 2nd retry: After 5 seconds
- 3rd retry: After 30 seconds
- 4th retry: After 2 minutes
- 5th retry: After 10 minutes
- Final retry: After 1 hour
Best practice: Respond with 200 OK as quickly as possible, then process the webhook asynchronously. This prevents timeouts and ensures reliable delivery.
Event Types
| Event | Trigger |
|---|---|
testimonial.submitted | When a new testimonial is submitted (before moderation) |
testimonial.approved(Coming soon) | When you approve a testimonial |
testimonial.rejected(Coming soon) | When you reject a testimonial |
Common Use Cases
Slack notifications
Post to Slack when new testimonials arrive for instant team visibility.
CRM sync
Automatically add testimonials to customer records in your CRM.
Email alerts
Send email notifications to your team or specific stakeholders.
Analytics tracking
Track testimonial submissions in your analytics platform.
Auto-approval workflow
Build custom moderation logic based on keywords or sender.
Content distribution
Automatically share approved testimonials on social media.