Overview
Introduction
Webhooks submit real-time user data to your own HTTP endpoints. A Webhook is an HTTP callback: a simple event-notification using HTTP POST. A web application implementing Webhooks will POST a message to a URL when certain things happen.
Getting started
- Go to Hub and click on Settings page
- On the right side of the page, your current Webhooks are displayed
- Click the "+" button
- Add the URL you would like to receive Webhooks to
- If you require authentication, add in a shared secret
Actions
PrintedDirect dispatches webhooks for different actions, such as when Jobs progress through the system, or when a JobBatch is dispatched.
PrintedDirect does not currently allow subscribing to specific actions at this time. This means you will receive a webhook for every action that has a webhook defined for it. Update June 2025: We now have support for subscribing to specific webhook actions. Please contact us if you would like to use this feature._
To view the actions that PrintedDirect sends, with example payloads, see the Actions page.
Webhook failures and timeouts
When receiving a webhook, your service must respond within 10 seconds or PrintedDirect will log this is a timeout error and will re-attempt after some time.
PrintedDirect Webhook system abides by 429 Too Many Requests
and will backoff and retry after a period of time. We will hold all new and pending webhooks to ensure they are delivered in chronological order once your system continues to accept our webhooks.
If we receive a non-2xx HTTP response code, we consider this a failure and will re-attempt it after some time. Therefore, it's important to always return a successful status even if you plan on discarding or ignoring the request. If you don't do this, we will continue to reattempt the failed webhook which will prevent newer webhooks from being delivered cause delays upstream.
Appendices
Authentication
If you want to authenticate the requests being sent to your webhook endpoint, you can specify a shared secret when creating your webhook. Once provided, PrintedDirect signs your requests using the shared secret and the body of the request, and add that as the X-Signature
header.
PrintedDirect calculates a SHA256 digest using the shared secret and the JSON-stringified body of the request.
An example of how one might authenticate the requests would be:
const signature = req.headers['x-signature'];
const digest = crypto
.createHmac('sha1', settings.sharedSecret)
.update(new Buffer(JSON.stringify(req.body), 'utf-8'))
.digest('hex');
if (signature === digest) {
// payload verified.
}
SSL certificates
PrintedDirect webhooks are incompatible with self-signed certificates. If we detect a self-signed certificate, it will generate an error, preventing any requests from being sent.