Webhooks

Overview

Webhooks notify your server when asynchronous operations complete — batch jobs finishing, large renders completing, or async conversions wrapping up. All webhook payloads are signed with HMAC-SHA256 so you can verify they came from PDFBase.

Setup

Configure webhook endpoints in your dashboard or via the API:

curl -X POST https://api.pdfbase.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer pk_live_xxx" \
  -d '{
    "url": "https://your-app.com/webhooks/pdfbase",
    "events": ["pdf.completed", "batch.completed", "batch.failed"]
  }'

{
  "id": "we_abc123",
  "object": "webhook_endpoint",
  "url": "https://your-app.com/webhooks/pdfbase",
  "events": ["pdf.completed", "batch.completed", "batch.failed"],
  "secret": "whsec_abc123def456",
  "status": "active",
  "created_at": "2026-05-19T10:00:00Z"
}

Store the secret securely. It’s only returned once at creation time. You’ll need it to verify webhook signatures.

Webhook payload

{
  "id": "evt_xyz789",
  "object": "event",
  "type": "pdf.completed",
  "created_at": "2026-05-19T10:30:05Z",
  "data": {
    "id": "pdf_x7Kf9m",
    "object": "pdf",
    "status": "completed",
    "url": "https://files.pdfbase.dev/pdf_x7Kf9m.pdf?token=sig_abc",
    "pages": 3,
    "bytes": 142000
  }
}

Verifying signatures

Every webhook request includes a PDFBase-Signature header:

PDFBase-Signature: t=1716120005,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Verify it by computing HMAC-SHA256 of {timestamp}.{raw_body} using your webhook secret:

import crypto from 'crypto'

function verifyWebhook(payload: string, header: string, secret: string): boolean {
  const [tPart, sigPart] = header.split(',')
  const timestamp = tPart.split('=')[1]
  const signature = sigPart.split('=')[1]

  // Reject if timestamp is more than 5 minutes old
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp)
  if (age > 300) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex')

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

import hmac
import hashlib
import time

def verify_webhook(payload: str, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp = parts["t"]
    signature = parts["v1"]

    # Reject if timestamp is more than 5 minutes old
    if int(time.time()) - int(timestamp) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{payload}".encode(),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Event types

Phase 1 (Launch)

Event	Fires when
`pdf.completed`	A PDF generation finishes successfully
`pdf.failed`	A PDF generation fails
`batch.completed`	All items in a batch job finish
`batch.failed`	A batch job fails (partial results may be available)
`batch.item.completed`	A single item within a batch finishes
`batch.item.failed`	A single item within a batch fails

Phase 2

Event	Fires when
`edit.completed`	A merge/split/watermark/compress operation finishes
`convert.completed`	A format conversion finishes

Phase 3

Event	Fires when
`extract.completed`	A text/OCR/table extraction finishes

Retry behavior

Failed webhook deliveries are retried with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the event is marked as failed and visible in your dashboard. You can manually retry from there. A delivery is considered failed if your endpoint:

Returns a non-2xx status code
Doesn’t respond within 15 seconds
Has a connection error

Testing webhooks

Use the dashboard’s Send test event button to fire a sample payload to your endpoint. Or use the CLI:

pdfbase webhooks test we_abc123 --event pdf.completed

Get Started

Core Concepts

Guides

Integrations

Resources

Overview

Setup

Webhook payload

Verifying signatures

Event types

Phase 1 (Launch)

Phase 2

Phase 3

Retry behavior

Testing webhooks

​Overview

​Setup

​Webhook payload

​Verifying signatures

​Event types

​Phase 1 (Launch)

​Phase 2

​Phase 3

​Retry behavior

​Testing webhooks

Overview

Setup

Webhook payload

Verifying signatures

Event types

Phase 1 (Launch)

Phase 2

Phase 3

Retry behavior

Testing webhooks