Comment on page
Webhooks
How to receive notifications when your jobs have completed by using 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
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.
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.
{
"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.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.
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.
Last modified 5yr ago