Webhook Events

PDF-Sign sends webhooks for various events. This page documents each event type and its payload structure.

Event Types

pdf.generated

Triggered when a PDF is successfully generated and stored.

Payload

{
  "event": "pdf.generated",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "data": {
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "pdf_url": "https://api.pdf-sign.com/storage/v1/object/public/pdfs/user-id/template-id/1705312245123.pdf",
    "storage_path": "user-id/template-id/1705312245123.pdf",
    "file_size": 156789,
    "render_time_ms": 2450,
    "variables": {
      "clientName": "John Doe",
      "invoiceNumber": "INV-2024-001",
      "amount": "1500.00"
    },
    "created_at": "2024-01-15T10:30:45.123Z"
  }
}

Fields

Example Use Cases

• Download and process the generated PDF
• Send the PDF to customers via email
• Store metadata in your database
• Trigger downstream workflows

pdf.failed

Triggered when PDF generation fails for any reason.

Payload

{
  "event": "pdf.failed",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "data": {
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": "RENDER_FAILED",
    "error_message": "Failed to render PDF: Template contains invalid HTML",
    "variables": {
      "clientName": "John Doe"
    }
  }
}

Fields

Error Codes

Example Use Cases

• Alert your team about failures
• Retry the generation with corrected data
• Log errors for debugging
• Notify affected customers

quota.warning

Triggered when usage reaches 80% of the monthly quota.

Payload

{
  "event": "quota.warning",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "data": {
    "current_usage": 240,
    "quota_limit": 300,
    "percentage": 80,
    "subscription_plan": "starter"
  }
}

Fields

Example Use Cases

• Send alert to administrators
• Display warning in your application
• Proactively upgrade the plan
• Pause non-critical PDF generation

quota.exceeded

Triggered when the monthly quota limit is reached and a PDF generation is blocked.

Payload

{
  "event": "quota.exceeded",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "data": {
    "current_usage": 300,
    "quota_limit": 300,
    "subscription_plan": "starter"
  }
}

Fields

Example Use Cases

• Immediately notify administrators
• Trigger plan upgrade workflow
• Pause PDF generation features
• Queue PDFs for next month

Handling Multiple Events

You can subscribe to multiple events with a single webhook. Handle them using a switch statement:

app.post('/webhooks/pdf-sign', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'pdf.generated':
      handlePdfGenerated(data);
      break;
    case 'pdf.failed':
      handlePdfFailed(data);
      break;
    case 'quota.warning':
      handleQuotaWarning(data);
      break;
    case 'quota.exceeded':
      handleQuotaExceeded(data);
      break;
    case 'test':
      console.log('Test webhook received');
      break;
    default:
      console.log(`Unknown event: ${event}`);
  }

  res.status(200).send('OK');
});

Event Timing