Webhooks

How to receive notifications when your jobs have completed by using webhooks.

Introduction to webhooks

Paperplane can send webhook events to notify your application when your PDF jobs have finished. Some of the use cases for webhooks are:

• To be alerted about any PDF jobs that failed.

• To take another action when the PDF has been generated, for example emailing the file or URL to a user.

• To avoid having to poll the jobs endpoint and wait for each PDF job to complete individually.

In order to receive webhook notifications, you'll need to:

1. Implement a webhook handler in your app.

2. Set up a new webhook subscription via the dashboard.

When are webhooks sent?

A webhook is sent when a job status changes to one of the following:

• delivered

• creation_failed

• delivery_failed

How to implement a webhook handler

To receive webhooks, you'll need to add a handler to your app and make it available at a public URL.

The webhook handler must:

1. Accept a POST request containing JSON data in the request body.

2. Return a response within 5 seconds, otherwise Paperplane will time out the request.

3. Return a response with a 200 or 2xx status code to indicate that the webhook has been processed.

Webhook retries

If your webhook handler responds with a non-200 status code, or is temporarily offline, then we'll try to re-deliver the webhook later.

Currently Paperplane will attempt up to 25 retries over the course of roughly 48 hours. After 25 failed attempts, we'll stop trying to deliver the webhook.

Webhook JSON example

{
  "id": "939d3fbc-ea35-4e58-983e-56e630b07246",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "delivered",
  "done": true,
  "object": "job",
  "webhook_id": "d08875b3-4401-425c-acf8-21dd40c95548"
}

The webhook provides the same data found at the jobs endpoint, with the addition of a webhook_id field.

Setting up a webhook subscription

Once you have a webhook handler in place, go to the Paperplane dashboard and add a new webhook subscription via the "Webhooks" section.

A webhook subscription is linked to an API key, and will only be sent webhooks for jobs created with that API key. However, you can create multiple subscriptions for different API keys that use the same endpoint.

Development tips

Whilst you're developing your webhook handler, you might find a service like ngrok useful for providing a public URL to a server that's running locally.