Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your PDF-Sign account.

Overview

When you configure a webhook, PDF-Sign will send an HTTP POST request to your specified URL whenever a subscribed event occurs. This enables you to:

• Automate workflows - Trigger actions in your system when PDFs are generated
• Monitor failures - Get instant alerts when PDF generation fails
• Track usage - Receive warnings when approaching quota limits
• Integrate seamlessly - Connect PDF-Sign with your existing tools and services

Quick Start

1. Create a Webhook

1. Log in to your PDF-Sign Dashboard
2. Navigate to Developer → Webhooks
3. Click Create Webhook
4. Enter your endpoint URL (must be HTTPS)
5. Select the events you want to subscribe to
6. Save your webhook and note the generated secret

2. Handle Webhook Requests

Your endpoint will receive POST requests with a JSON payload:

{
  "event": "pdf.generated",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "data": {
    "template_id": "uuid",
    "pdf_url": "https://api.pdf-sign.com/storage/...",
    "file_size": 156789,
    "render_time_ms": 2450
  }
}

3. Verify the Request

Always verify the X-Webhook-Secret header matches your webhook secret:

const secret = req.headers['x-webhook-secret'];
if (secret !== process.env.WEBHOOK_SECRET) {
  return res.status(401).send('Unauthorized');
}

Available Events

See Events for detailed payload information.

Webhook Headers

Each webhook request includes these headers:

Testing Webhooks

You can send a test webhook from the dashboard:

1. Go to Developer → Webhooks
2. Find your webhook in the list
3. Click the menu (three dots) → Send Test

The test payload looks like:

{
  "event": "test",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "data": {
    "message": "This is a test webhook from PDF-Sign",
    "webhook_id": "uuid",
    "webhook_name": "My Webhook",
    "subscribed_events": ["pdf.generated", "pdf.failed"]
  }
}

Best Practices

1. Respond quickly - Return a 2xx status within 5 seconds
2. Process asynchronously - Queue long-running tasks instead of blocking
3. Handle duplicates - Use idempotent processing in case of retries
4. Verify secrets - Always validate the X-Webhook-Secret header
5. Use HTTPS - Webhook URLs must use HTTPS for security

Example Endpoint

Here's a complete example of a webhook endpoint in Node.js:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/pdf-sign', (req, res) => {
  // Verify webhook secret
  const secret = req.headers['x-webhook-secret'];
  if (secret !== process.env.PDF_SIGN_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Invalid secret' });
  }

  const { event, timestamp, data } = req.body;

  switch (event) {
    case 'pdf.generated':
      console.log(`PDF generated: ${data.pdf_url}`);
      // Process the generated PDF...
      break;
    case 'pdf.failed':
      console.error(`PDF generation failed: ${data.error_message}`);
      // Handle the error...
      break;
    case 'quota.warning':
      console.warn(`Quota warning: ${data.percentage}% used`);
      // Send alert to team...
      break;
    case 'quota.exceeded':
      console.error('Quota exceeded!');
      // Upgrade plan or pause operations...
      break;
  }

  res.status(200).json({ received: true });
});

app.listen(3000);

Next Steps

• Events - Detailed event payloads
• Security - Security best practices