Webhooks: Receive Real-Time Document Generation Notifications

Last updated March 23, 2026

Webhooks let you receive an HTTP notification whenever a document finishes generating, so you can react immediately without polling the API. PDFMonkey uses Svix to deliver webhooks with automatic retries and signature verification.

This page covers event types, the webhook payload format, how to configure endpoint routing (workspace-wide, template-specific, or custom channels), and how to verify webhook signatures.

Event types

PDFMonkey fires two webhook event types:

EventWhen it fires
documents.generation.successA document has been generated successfully. The download_url is available.
documents.generation.failureA document failed to generate. The failure_cause field describes what went wrong.

Subscribe to one or both depending on your needs. Most integrations subscribe to documents.generation.success at minimum.

Webhook payload

Every webhook delivers a DocumentCard object wrapped in a document key:

{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "document_template_identifier": "My Invoice Template",
    "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/...",
    "failure_cause": null,
    "filename": "2050-03-14 Peter Parker.pdf",
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "preview_url": "https://preview.pdfmonkey.io/...",
    "public_share_link": null,
    "status": "success",
    "updated_at": "2050-03-13T12:34:59.412+02:00"
  }
}

DocumentCard, not Document

The webhook payload is a DocumentCard, not a full Document. It does not include the payload (dynamic data), generation_logs, or checksum fields. If you need to pass data through to your webhook handler, use the meta field when creating the document. See The DocumentCard Object for a full attribute reference.

Set up a workspace-wide webhook

To receive notifications for every document generated in a workspace:

  1. Click the Webhooks link in the main navigation.
  2. Click the + Add Endpoint button.
  3. Enter your endpoint URL.
  4. Select the event type(s) you want to receive (documents.generation.success, documents.generation.failure, or both).

Your endpoint is now called whenever any document in the workspace finishes generating.

Set up a template-specific webhook

In many cases (particularly when using no-code platforms like Zapier, Make, or n8n), you need a webhook that fires only for a specific template.

  1. Copy the ID of the template you want to target.
  2. Click the Webhooks link in the main navigation.
  3. Click the + Add Endpoint button.
  4. Enter your endpoint URL and select the event type(s).
  5. In the channels field, add template-YOUR_TEMPLATE_ID.
template-07C63E0B-620F-44A9-AF9F-4CA0DA025A0A

Your endpoint is now called only when a document is generated from that specific template.

Channels are case-sensitive

When adding a template or folder ID to the channels list, always paste it in upper-case. A lower-case ID will silently fail to match, and your endpoint will never be called.

Target multiple templates or a folder

If you need the same webhook endpoint for several templates but not all of them, you can add up to 3 channels to a single endpoint.

If 3 channels are not enough, group the templates in a folder and use the folder ID as a channel. This way, any template in that folder triggers the webhook.

Follow the same steps as above, but add folder-YOUR_FOLDER_ID in the channels list:

folder-440DA20B-C5A0-A0A9-C62F-4070FAF963EA

Custom channels via meta

You can route webhooks dynamically on a per-document basis by setting the _webhook_channel key in the document’s meta field. This adds an extra channel to the webhook notification for that specific document.

{
  "document": {
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "payload": "{}",
    "status": "pending",
    "meta": "{\"_webhook_channel\": \"order-42\"}"
  }
}

Then configure a webhook endpoint with order-42 as a channel. Only documents that include this value in their meta will trigger that endpoint.

Combine with template channels

A document’s webhook notification always includes its template channel (and folder channel, if applicable) in addition to any custom channel from meta. This means a single webhook event can match multiple endpoints.

Verify webhook signatures

Because webhooks are HTTP requests sent to a public URL, an attacker could impersonate PDFMonkey by sending a fake request to your endpoint. To prevent this, Svix signs every webhook with a unique secret key for each endpoint.

You should verify the signature on every incoming webhook before processing it. Svix provides libraries for popular languages that handle verification in a few lines of code.

Learn how to verify signatures in Svix’s verification documentation.

Always verify in production

Skipping signature verification exposes your endpoint to spoofed requests. Always verify the webhook signature before acting on the payload.

Frequently asked questions

Do webhooks work with image generation?

Yes. Webhooks fire for all output formats (PDF, PNG, JPG, WebP). The event types are the same regardless of output type.

Is the download_url in the webhook payload permanent?

No. The download_url is a temporary signed link valid for 1 hour. Download the file immediately when you receive the webhook, or fetch a fresh URL later via the API. See The Download URL for details.

Does the webhook include the original dynamic data (payload)?

No. The webhook delivers a DocumentCard, which omits the payload field. Store any data you need in the meta field when creating the document; meta is included in the webhook.

What happens if my endpoint is down?

Svix automatically retries failed deliveries with exponential backoff over several hours. You can monitor delivery attempts and manually replay failed messages from the Webhooks section in the PDFMonkey dashboard.

How do I test webhooks during development?

Use a tunneling service like ngrok or localtunnel to expose your local server to the internet. Point your webhook endpoint at the tunnel URL, then generate a test document from the Dashboard.

Can I use the synchronous endpoint instead of webhooks?

Yes. The /api/v1/documents/sync endpoint waits for generation to complete and returns the result in a single request. This is convenient for prototyping but has a 6-minute timeout. For production workloads, webhooks are more reliable and scalable. See Synchronous Generation.

Frequently asked questions

What data does PDFMonkey send in a webhook?
PDFMonkey sends a DocumentCard object wrapped in a "document" key. It includes the document ID, status, download URL, filename, meta, output type, template ID, and more. The payload does not include the original dynamic data — use the meta field to pass through any data you need in the webhook.
How do I verify that a webhook really comes from PDFMonkey?
PDFMonkey uses Svix to deliver webhooks. Every webhook is signed with a unique key for each endpoint. You can verify the signature using Svix's official libraries for Node.js, Python, Ruby, Go, and other languages.
Can I receive webhooks for only specific templates?
Yes. When creating a webhook endpoint, add a channel in the format template-YOUR_TEMPLATE_ID to filter notifications to a specific template. You can also use folder-YOUR_FOLDER_ID to receive webhooks for all templates in a folder.
Does PDFMonkey send webhooks for failed documents?
Yes. PDFMonkey fires two event types: documents.generation.success when a document is generated successfully, and documents.generation.failure when generation fails. Subscribe to both to handle errors in your integration.
What happens if my webhook endpoint is down?
Svix automatically retries failed deliveries with exponential backoff over several hours. You can monitor delivery attempts and manually replay failed messages from the Webhooks section in the PDFMonkey dashboard.
Navigation